Commit 0c9aa209 authored Nov 16, 2016 by Jani Nikula Committed by Jonathan Corbet Nov 16, 2016

kernel-doc: add support for one line inline struct member doc comments



kernel-doc supports documenting struct members "inline" since
a4c6ebed ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/**
		 * @bar: member documentation
		 */
		int bar;
	};

Add support for one line inline comments:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/** @bar: member documentation */
		int bar;
	};

Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.

Cc: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

parent dc92726e

scripts/kernel-doc

+11 −1

Original line number	Diff line number	Diff line
		@@ -421,6 +421,7 @@ my $doc_block = $doc_com . 'DOC:\s(.)?';
		my $doc_inline_start = '^\s/\\\s$';
		my $doc_inline_sect = '\s\\s(@[\w\s]+):(.)';
		my $doc_inline_end = '^\s\/\s*$';
		my $doc_inline_oneline = '^\s/\\\s(@[\w\s]+):\s(.)\s\/\s*$';
		my $export_symbol = '^\sEXPORT_SYMBOL(_GPL)?\s$\s(\w+)\s$\s*;';

		my %parameterdescs;
		@@ -3024,7 +3025,16 @@ sub process_file($) {
		}
		}
		} elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
		if (/$doc_inline_start/) {
		if (/$doc_inline_oneline/) {
		$section = $1;
		$contents = $2;
		if ($contents ne "") {
		$contents .= "\n";
		dump_section($file, $section, xml_escape($contents));
		$section = $section_default;
		$contents = "";
		}
		} elsif (/$doc_inline_start/) {
		$state = STATE_INLINE;
		$inline_doc_state = STATE_INLINE_NAME;
		} elsif ($decl_type eq 'function') {

Admin message