kernel-doc (60004ca5dcfbf43182a9ba42bcbbf216c3684433) kernel-doc (a4c6ebede2f99fc3aaa5a42228a16747d0aa2504)
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

--- 119 unchanged lines hidden (view full) ---

128# int a;
129# int b;
130# /* private: */
131# int c;
132# };
133#
134# All descriptions can be multiline, except the short function description.
135#
1#!/usr/bin/perl -w
2
3use strict;
4
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ##

--- 119 unchanged lines hidden (view full) ---

128# int a;
129# int b;
130# /* private: */
131# int c;
132# };
133#
134# All descriptions can be multiline, except the short function description.
135#
136# For really longs structs, you can also describe arguments inside the
137# body of the struct.
138# eg.
139# /**
140# * struct my_struct - short description
141# * @a: first member
142# * @b: second member
143# *
144# * Longer description
145# */
146# struct my_struct {
147# int a;
148# int b;
149# /**
150# * @c: This is longer description of C
151# *
152# * You can use paragraphs to describe arguments
153# * using this method.
154# */
155# int c;
156# };
157#
158# This should be use only for struct/enum members.
159#
136# You can also add additional sections. When documenting kernel functions you
137# should document the "Context:" of the function, e.g. whether the functions
138# can be called form interrupts. Unlike other sections you can end it with an
139# empty line.
140# A non-void function should have a "Return:" section describing the return
141# value(s).
142# Example-sections should contain the string EXAMPLE so that they are marked
143# appropriately in DocBook.

--- 147 unchanged lines hidden (view full) ---

291my $lineprefix="";
292
293# states
294# 0 - normal code
295# 1 - looking for function name
296# 2 - scanning field start.
297# 3 - scanning prototype.
298# 4 - documentation block
160# You can also add additional sections. When documenting kernel functions you
161# should document the "Context:" of the function, e.g. whether the functions
162# can be called form interrupts. Unlike other sections you can end it with an
163# empty line.
164# A non-void function should have a "Return:" section describing the return
165# value(s).
166# Example-sections should contain the string EXAMPLE so that they are marked
167# appropriately in DocBook.

--- 147 unchanged lines hidden (view full) ---

315my $lineprefix="";
316
317# states
318# 0 - normal code
319# 1 - looking for function name
320# 2 - scanning field start.
321# 3 - scanning prototype.
322# 4 - documentation block
323# 5 - gathering documentation outside main block
299my $state;
300my $in_doc_sect;
301
324my $state;
325my $in_doc_sect;
326
327# Split Doc State
328# 0 - Invalid (Before start or after finish)
329# 1 - Is started (the /** was found inside a struct)
330# 2 - The @parameter header was found, start accepting multi paragraph text.
331# 3 - Finished (the */ was found)
332# 4 - Error - Comment without header was found. Spit a warning as it's not
333# proper kernel-doc and ignore the rest.
334my $split_doc_state;
335
302#declaration types: can be
303# 'function', 'struct', 'union', 'enum', 'typedef'
304my $decl_type;
305
306my $doc_special = "\@\%\$\&";
307
308my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
309my $doc_end = '\*/';
310my $doc_com = '\s*\*\s*';
311my $doc_com_body = '\s*\* ?';
312my $doc_decl = $doc_com . '(\w+)';
313my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
314my $doc_content = $doc_com_body . '(.*)';
315my $doc_block = $doc_com . 'DOC:\s*(.*)?';
336#declaration types: can be
337# 'function', 'struct', 'union', 'enum', 'typedef'
338my $decl_type;
339
340my $doc_special = "\@\%\$\&";
341
342my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
343my $doc_end = '\*/';
344my $doc_com = '\s*\*\s*';
345my $doc_com_body = '\s*\* ?';
346my $doc_decl = $doc_com . '(\w+)';
347my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
348my $doc_content = $doc_com_body . '(.*)';
349my $doc_block = $doc_com . 'DOC:\s*(.*)?';
350my $doc_split_start = '^\s*/\*\*\s*$';
351my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
352my $doc_split_end = '^\s*\*/\s*$';
316
317my %constants;
318my %parameterdescs;
319my @parameterlist;
320my %sections;
321my @sectionlist;
322my $sectcheck;
323my $struct_actual;

--- 1861 unchanged lines hidden (view full) ---

2185 @parameterlist = ();
2186 %sections = ();
2187 @sectionlist = ();
2188 $sectcheck = "";
2189 $struct_actual = "";
2190 $prototype = "";
2191
2192 $state = 0;
353
354my %constants;
355my %parameterdescs;
356my @parameterlist;
357my %sections;
358my @sectionlist;
359my $sectcheck;
360my $struct_actual;

--- 1861 unchanged lines hidden (view full) ---

2222 @parameterlist = ();
2223 %sections = ();
2224 @sectionlist = ();
2225 $sectcheck = "";
2226 $struct_actual = "";
2227 $prototype = "";
2228
2229 $state = 0;
2230 $split_doc_state = 0;
2193}
2194
2195sub tracepoint_munge($) {
2196 my $file = shift;
2197 my $tracepointname = 0;
2198 my $tracepointargs = 0;
2199
2200 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

--- 256 unchanged lines hidden (view full) ---

2457 while ((substr($contents, 0, 1) eq " ") ||
2458 substr($contents, 0, 1) eq "\t") {
2459 $contents = substr($contents, 1);
2460 }
2461 $contents .= "\n";
2462 }
2463 $section = $newsection;
2464 } elsif (/$doc_end/) {
2231}
2232
2233sub tracepoint_munge($) {
2234 my $file = shift;
2235 my $tracepointname = 0;
2236 my $tracepointargs = 0;
2237
2238 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

--- 256 unchanged lines hidden (view full) ---

2495 while ((substr($contents, 0, 1) eq " ") ||
2496 substr($contents, 0, 1) eq "\t") {
2497 $contents = substr($contents, 1);
2498 }
2499 $contents .= "\n";
2500 }
2501 $section = $newsection;
2502 } elsif (/$doc_end/) {
2465
2466 if (($contents ne "") && ($contents ne "\n")) {
2467 dump_section($file, $section, xml_escape($contents));
2468 $section = $section_default;
2469 $contents = "";
2470 }
2471 # look for doc_com + <text> + doc_end:
2472 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2473 print STDERR "Warning(${file}:$.): suspicious ending line: $_";

--- 24 unchanged lines hidden (view full) ---

2498 } else {
2499 $contents .= $1 . "\n";
2500 }
2501 } else {
2502 # i dont know - bad line? ignore.
2503 print STDERR "Warning(${file}:$.): bad line: $_";
2504 ++$warnings;
2505 }
2503 if (($contents ne "") && ($contents ne "\n")) {
2504 dump_section($file, $section, xml_escape($contents));
2505 $section = $section_default;
2506 $contents = "";
2507 }
2508 # look for doc_com + <text> + doc_end:
2509 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2510 print STDERR "Warning(${file}:$.): suspicious ending line: $_";

--- 24 unchanged lines hidden (view full) ---

2535 } else {
2536 $contents .= $1 . "\n";
2537 }
2538 } else {
2539 # i dont know - bad line? ignore.
2540 print STDERR "Warning(${file}:$.): bad line: $_";
2541 ++$warnings;
2542 }
2543 } elsif ($state == 5) { # scanning for split parameters
2544 # First line (state 1) needs to be a @parameter
2545 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2546 $section = $1;
2547 $contents = $2;
2548 if ($contents ne "") {
2549 while ((substr($contents, 0, 1) eq " ") ||
2550 substr($contents, 0, 1) eq "\t") {
2551 $contents = substr($contents, 1);
2552 }
2553 $contents .= "\n";
2554 }
2555 $split_doc_state = 2;
2556 # Documentation block end */
2557 } elsif (/$doc_split_end/) {
2558 if (($contents ne "") && ($contents ne "\n")) {
2559 dump_section($file, $section, xml_escape($contents));
2560 $section = $section_default;
2561 $contents = "";
2562 }
2563 $state = 3;
2564 $split_doc_state = 0;
2565 # Regular text
2566 } elsif (/$doc_content/) {
2567 if ($split_doc_state == 2) {
2568 $contents .= $1 . "\n";
2569 } elsif ($split_doc_state == 1) {
2570 $split_doc_state = 4;
2571 print STDERR "Warning(${file}:$.): ";
2572 print STDERR "Incorrect use of kernel-doc format: $_";
2573 ++$warnings;
2574 }
2575 }
2506 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2576 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2507 if ($decl_type eq 'function') {
2577 if (/$doc_split_start/) {
2578 $state = 5;
2579 $split_doc_state = 1;
2580 } elsif ($decl_type eq 'function') {
2508 process_state3_function($_, $file);
2509 } else {
2510 process_state3_type($_, $file);
2511 }
2512 } elsif ($state == 4) {
2513 # Documentation block
2514 if (/$doc_block/) {
2515 dump_doc_section($file, $section, xml_escape($contents));

--- 113 unchanged lines hidden --- 		2581 process_state3_function($_, $file);
2582 } else {
2583 process_state3_type($_, $file);
2584 }
2585 } elsif ($state == 4) {
2586 # Documentation block
2587 if (/$doc_block/) {
2588 dump_doc_section($file, $section, xml_escape($contents));

--- 113 unchanged lines hidden ---