p71924506
/
linux_old1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

kernel-doc supports documenting struct members "inline" since
a4c6ebede2 ("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>
This commit is contained in:
Jani Nikula 2016-11-16 17:26:16 +02:00 committed by Jonathan Corbet
parent dc92726e7f
commit 0c9aa20957
1 changed files with 11 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
scripts/kernel-doc
View File

@ -421,6 +421,7 @@ my $doc_block = $doc_com . 'DOC:\s*(.*)?';
my $doc_inline_start = '^\s*/\*\*\s*$'; my $doc_inline_start = '^\s*/\*\*\s*$';
my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)'; my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
my $doc_inline_end = '^\s*\*/\s*$'; my $doc_inline_end = '^\s*\*/\s*$';
my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
my %parameterdescs; my %parameterdescs;
@ -3024,7 +3025,16 @@ sub process_file($) {
} }
} }
} elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype) } 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; $state = STATE_INLINE;
$inline_doc_state = STATE_INLINE_NAME; $inline_doc_state = STATE_INLINE_NAME;
} elsif ($decl_type eq 'function') { } elsif ($decl_type eq 'function') {