kernel-doc (86ae2e38d40ed6bf7c907d126053e6f4b1dc5b6e) kernel-doc (48af606ad8912f90e1539621a26e86672976d8ae)
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 ##

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

345# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
346# We keep track of number of generated entries and generate a dummy
347# if needs be to ensure the expanded template can be postprocessed
348# into html.
349my $section_counter = 0;
350
351my $lineprefix="";
352
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 ##

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

345# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
346# We keep track of number of generated entries and generate a dummy
347# if needs be to ensure the expanded template can be postprocessed
348# into html.
349my $section_counter = 0;
350
351my $lineprefix="";
352
353# states
354# 0 - normal code
355# 1 - looking for function name
356# 2 - scanning field start.
357# 3 - scanning prototype.
358# 4 - documentation block
359# 5 - gathering documentation outside main block
353# Parser states
354use constant {
355 STATE_NORMAL => 0, # normal code
356 STATE_NAME => 1, # looking for function name
357 STATE_FIELD => 2, # scanning field start
358 STATE_PROTO => 3, # scanning prototype
359 STATE_DOCBLOCK => 4, # documentation block
360 STATE_INLINE => 5, # gathering documentation outside main block
361};
360my $state;
361my $in_doc_sect;
362
362my $state;
363my $in_doc_sect;
364
363# Split Doc State
364# 0 - Invalid (Before start or after finish)
365# 1 - Is started (the /** was found inside a struct)
366# 2 - The @parameter header was found, start accepting multi paragraph text.
367# 3 - Finished (the */ was found)
368# 4 - Error - Comment without header was found. Spit a warning as it's not
369# proper kernel-doc and ignore the rest.
370my $split_doc_state;
365# Inline documentation state
366use constant {
367 STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)
368 STATE_INLINE_NAME => 1, # looking for member name (@foo:)
369 STATE_INLINE_TEXT => 2, # looking for member documentation
370 STATE_INLINE_END => 3, # done
371 STATE_INLINE_ERROR => 4, # error - Comment without header was found.
372 # Spit a warning as it's not
373 # proper kernel-doc and ignore the rest.
374};
375my $inline_doc_state;
371
372#declaration types: can be
373# 'function', 'struct', 'union', 'enum', 'typedef'
374my $decl_type;
375
376my $doc_special = "\@\%\$\&";
377
378my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
379my $doc_end = '\*/';
380my $doc_com = '\s*\*\s*';
381my $doc_com_body = '\s*\* ?';
382my $doc_decl = $doc_com . '(\w+)';
383my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
384my $doc_content = $doc_com_body . '(.*)';
385my $doc_block = $doc_com . 'DOC:\s*(.*)?';
376
377#declaration types: can be
378# 'function', 'struct', 'union', 'enum', 'typedef'
379my $decl_type;
380
381my $doc_special = "\@\%\$\&";
382
383my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
384my $doc_end = '\*/';
385my $doc_com = '\s*\*\s*';
386my $doc_com_body = '\s*\* ?';
387my $doc_decl = $doc_com . '(\w+)';
388my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
389my $doc_content = $doc_com_body . '(.*)';
390my $doc_block = $doc_com . 'DOC:\s*(.*)?';
386my $doc_split_start = '^\s*/\*\*\s*$';
387my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
388my $doc_split_end = '^\s*\*/\s*$';
391my $doc_inline_start = '^\s*/\*\*\s*$';
392my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
393my $doc_inline_end = '^\s*\*/\s*$';
389my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
390
391my %constants;
392my %parameterdescs;
393my @parameterlist;
394my %sections;
395my @sectionlist;
396my $sectcheck;

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

2492 %parametertypes = ();
2493 @parameterlist = ();
2494 %sections = ();
2495 @sectionlist = ();
2496 $sectcheck = "";
2497 $struct_actual = "";
2498 $prototype = "";
2499
394my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
395
396my %constants;
397my %parameterdescs;
398my @parameterlist;
399my %sections;
400my @sectionlist;
401my $sectcheck;

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

2497 %parametertypes = ();
2498 @parameterlist = ();
2499 %sections = ();
2500 @sectionlist = ();
2501 $sectcheck = "";
2502 $struct_actual = "";
2503 $prototype = "";
2504
2500 $state = 0;
2501 $split_doc_state = 0;
2505 $state = STATE_NORMAL;
2506 $inline_doc_state = STATE_INLINE_NA;
2502}
2503
2504sub tracepoint_munge($) {
2505 my $file = shift;
2506 my $tracepointname = 0;
2507 my $tracepointargs = 0;
2508
2509 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

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

2702
2703 $. = 1;
2704
2705 $section_counter = 0;
2706 while (<IN>) {
2707 while (s/\\\s*$//) {
2708 $_ .= <IN>;
2709 }
2507}
2508
2509sub tracepoint_munge($) {
2510 my $file = shift;
2511 my $tracepointname = 0;
2512 my $tracepointargs = 0;
2513
2514 if ($prototype =~ m/TRACE_EVENT\((.*?),/) {

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

2707
2708 $. = 1;
2709
2710 $section_counter = 0;
2711 while (<IN>) {
2712 while (s/\\\s*$//) {
2713 $_ .= <IN>;
2714 }
2710 if ($state == 0) {
2715 if ($state == STATE_NORMAL) {
2711 if (/$doc_start/o) {
2716 if (/$doc_start/o) {
2712 $state = 1; # next line is always the function name
2717 $state = STATE_NAME; # next line is always the function name
2713 $in_doc_sect = 0;
2714 }
2718 $in_doc_sect = 0;
2719 }
2715 } elsif ($state == 1) { # this line is the function name (always)
2720 } elsif ($state == STATE_NAME) {# this line is the function name (always)
2716 if (/$doc_block/o) {
2721 if (/$doc_block/o) {
2717 $state = 4;
2722 $state = STATE_DOCBLOCK;
2718 $contents = "";
2719 if ( $1 eq "" ) {
2720 $section = $section_intro;
2721 } else {
2722 $section = $1;
2723 }
2724 }
2725 elsif (/$doc_decl/o) {
2726 $identifier = $1;
2727 if (/\s*([\w\s]+?)\s*-/) {
2728 $identifier = $1;
2729 }
2730
2723 $contents = "";
2724 if ( $1 eq "" ) {
2725 $section = $section_intro;
2726 } else {
2727 $section = $1;
2728 }
2729 }
2730 elsif (/$doc_decl/o) {
2731 $identifier = $1;
2732 if (/\s*([\w\s]+?)\s*-/) {
2733 $identifier = $1;
2734 }
2735
2731 $state = 2;
2736 $state = STATE_FIELD;
2732 if (/-(.*)/) {
2733 # strip leading/trailing/multiple spaces
2734 $descr= $1;
2735 $descr =~ s/^\s*//;
2736 $descr =~ s/\s*$//;
2737 $descr =~ s/\s+/ /g;
2738 $declaration_purpose = xml_escape($descr);
2739 $in_purpose = 1;

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

2761
2762 if ($verbose) {
2763 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2764 }
2765 } else {
2766 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2767 " - I thought it was a doc line\n";
2768 ++$warnings;
2737 if (/-(.*)/) {
2738 # strip leading/trailing/multiple spaces
2739 $descr= $1;
2740 $descr =~ s/^\s*//;
2741 $descr =~ s/\s*$//;
2742 $descr =~ s/\s+/ /g;
2743 $declaration_purpose = xml_escape($descr);
2744 $in_purpose = 1;

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

2766
2767 if ($verbose) {
2768 print STDERR "${file}:$.: info: Scanning doc for $identifier\n";
2769 }
2770 } else {
2771 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2772 " - I thought it was a doc line\n";
2773 ++$warnings;
2769 $state = 0;
2774 $state = STATE_NORMAL;
2770 }
2775 }
2771 } elsif ($state == 2) { # look for head: lines, and include content
2776 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
2772 if (/$doc_sect/o) {
2773 $newsection = $1;
2774 $newcontents = $2;
2775
2776 if (($contents ne "") && ($contents ne "\n")) {
2777 if (!$in_doc_sect && $verbose) {
2778 print STDERR "${file}:$.: warning: contents before sections\n";
2779 ++$warnings;

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

2801 }
2802 # look for doc_com + <text> + doc_end:
2803 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2804 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2805 ++$warnings;
2806 }
2807
2808 $prototype = "";
2777 if (/$doc_sect/o) {
2778 $newsection = $1;
2779 $newcontents = $2;
2780
2781 if (($contents ne "") && ($contents ne "\n")) {
2782 if (!$in_doc_sect && $verbose) {
2783 print STDERR "${file}:$.: warning: contents before sections\n";
2784 ++$warnings;

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

2806 }
2807 # look for doc_com + <text> + doc_end:
2808 if ($_ =~ m'\s*\*\s*[a-zA-Z_0-9:\.]+\*/') {
2809 print STDERR "${file}:$.: warning: suspicious ending line: $_";
2810 ++$warnings;
2811 }
2812
2813 $prototype = "";
2809 $state = 3;
2814 $state = STATE_PROTO;
2810 $brcount = 0;
2811# print STDERR "end of doc comment, looking for prototype\n";
2812 } elsif (/$doc_content/) {
2813 # miguel-style comment kludge, look for blank lines after
2814 # @parameter line to signify start of description
2815 if ($1 eq "") {
2816 if ($section =~ m/^@/ || $section eq $section_context) {
2817 dump_section($file, $section, xml_escape($contents));

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

2829 } else {
2830 $contents .= $1 . "\n";
2831 }
2832 } else {
2833 # i dont know - bad line? ignore.
2834 print STDERR "${file}:$.: warning: bad line: $_";
2835 ++$warnings;
2836 }
2815 $brcount = 0;
2816# print STDERR "end of doc comment, looking for prototype\n";
2817 } elsif (/$doc_content/) {
2818 # miguel-style comment kludge, look for blank lines after
2819 # @parameter line to signify start of description
2820 if ($1 eq "") {
2821 if ($section =~ m/^@/ || $section eq $section_context) {
2822 dump_section($file, $section, xml_escape($contents));

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

2834 } else {
2835 $contents .= $1 . "\n";
2836 }
2837 } else {
2838 # i dont know - bad line? ignore.
2839 print STDERR "${file}:$.: warning: bad line: $_";
2840 ++$warnings;
2841 }
2837 } elsif ($state == 5) { # scanning for split parameters
2842 } elsif ($state == STATE_INLINE) { # scanning for inline parameters
2838 # First line (state 1) needs to be a @parameter
2843 # First line (state 1) needs to be a @parameter
2839 if ($split_doc_state == 1 && /$doc_split_sect/o) {
2844 if ($inline_doc_state == STATE_INLINE_NAME && /$doc_inline_sect/o) {
2840 $section = $1;
2841 $contents = $2;
2842 if ($contents ne "") {
2843 while ((substr($contents, 0, 1) eq " ") ||
2844 substr($contents, 0, 1) eq "\t") {
2845 $contents = substr($contents, 1);
2846 }
2847 $contents .= "\n";
2848 }
2845 $section = $1;
2846 $contents = $2;
2847 if ($contents ne "") {
2848 while ((substr($contents, 0, 1) eq " ") ||
2849 substr($contents, 0, 1) eq "\t") {
2850 $contents = substr($contents, 1);
2851 }
2852 $contents .= "\n";
2853 }
2849 $split_doc_state = 2;
2854 $inline_doc_state = STATE_INLINE_TEXT;
2850 # Documentation block end */
2855 # Documentation block end */
2851 } elsif (/$doc_split_end/) {
2856 } elsif (/$doc_inline_end/) {
2852 if (($contents ne "") && ($contents ne "\n")) {
2853 dump_section($file, $section, xml_escape($contents));
2854 $section = $section_default;
2855 $contents = "";
2856 }
2857 if (($contents ne "") && ($contents ne "\n")) {
2858 dump_section($file, $section, xml_escape($contents));
2859 $section = $section_default;
2860 $contents = "";
2861 }
2857 $state = 3;
2858 $split_doc_state = 0;
2862 $state = STATE_PROTO;
2863 $inline_doc_state = STATE_INLINE_NA;
2859 # Regular text
2860 } elsif (/$doc_content/) {
2864 # Regular text
2865 } elsif (/$doc_content/) {
2861 if ($split_doc_state == 2) {
2866 if ($inline_doc_state == STATE_INLINE_TEXT) {
2862 $contents .= $1 . "\n";
2867 $contents .= $1 . "\n";
2863 } elsif ($split_doc_state == 1) {
2864 $split_doc_state = 4;
2868 } elsif ($inline_doc_state == STATE_INLINE_NAME) {
2869 $inline_doc_state = STATE_INLINE_ERROR;
2865 print STDERR "Warning(${file}:$.): ";
2866 print STDERR "Incorrect use of kernel-doc format: $_";
2867 ++$warnings;
2868 }
2869 }
2870 print STDERR "Warning(${file}:$.): ";
2871 print STDERR "Incorrect use of kernel-doc format: $_";
2872 ++$warnings;
2873 }
2874 }
2870 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2871 if (/$doc_split_start/) {
2872 $state = 5;
2873 $split_doc_state = 1;
2875 } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype)
2876 if (/$doc_inline_start/) {
2877 $state = STATE_INLINE;
2878 $inline_doc_state = STATE_INLINE_NAME;
2874 } elsif ($decl_type eq 'function') {
2875 process_state3_function($_, $file);
2876 } else {
2877 process_state3_type($_, $file);
2878 }
2879 } elsif ($decl_type eq 'function') {
2880 process_state3_function($_, $file);
2881 } else {
2882 process_state3_type($_, $file);
2883 }
2879 } elsif ($state == 4) {
2884 } elsif ($state == STATE_DOCBLOCK) {
2880 # Documentation block
2881 if (/$doc_block/) {
2882 dump_doc_section($file, $section, xml_escape($contents));
2883 $contents = "";
2884 $function = "";
2885 %constants = ();
2886 %parameterdescs = ();
2887 %parametertypes = ();

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

2902 $function = "";
2903 %constants = ();
2904 %parameterdescs = ();
2905 %parametertypes = ();
2906 @parameterlist = ();
2907 %sections = ();
2908 @sectionlist = ();
2909 $prototype = "";
2885 # Documentation block
2886 if (/$doc_block/) {
2887 dump_doc_section($file, $section, xml_escape($contents));
2888 $contents = "";
2889 $function = "";
2890 %constants = ();
2891 %parameterdescs = ();
2892 %parametertypes = ();

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

2907 $function = "";
2908 %constants = ();
2909 %parameterdescs = ();
2910 %parametertypes = ();
2911 @parameterlist = ();
2912 %sections = ();
2913 @sectionlist = ();
2914 $prototype = "";
2910 $state = 0;
2915 $state = STATE_NORMAL;
2911 }
2912 elsif (/$doc_content/)
2913 {
2914 if ( $1 eq "" )
2915 {
2916 $contents .= $blankline;
2917 }
2918 else

--- 79 unchanged lines hidden --- 		2916 }
2917 elsif (/$doc_content/)
2918 {
2919 if ( $1 eq "" )
2920 {
2921 $contents .= $blankline;
2922 }
2923 else

--- 79 unchanged lines hidden ---