kernel-doc: add support for one line inline struct member doc comments
authorJani Nikula <jani.nikula@intel.com>
Wed, 16 Nov 2016 15:26:16 +0000 (17:26 +0200)
committerJonathan Corbet <corbet@lwn.net>
Wed, 16 Nov 2016 23:30:27 +0000 (16:30 -0700)
kernel-doc supports documenting struct members "inline" since
a4c6ebede2f9 ("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>
scripts/kernel-doc

index e10378f769f9e235db0b7f0bb53236fa368f1c62..030fc633acd4ab11c7b12ff942601a820fe1fab8 100755 (executable)
@@ -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 = '^\s*EXPORT_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') {