kernel-doc (cddfe325afedb67a15fbe1a91e82ffed40236413) kernel-doc (f624adef3d0b9975076c1ba7549b81ed19e34437)
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 ##

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

396# 'function', 'struct', 'union', 'enum', 'typedef'
397my $decl_type;
398
399my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
400my $doc_end = '\*/';
401my $doc_com = '\s*\*\s*';
402my $doc_com_body = '\s*\* ?';
403my $doc_decl = $doc_com . '(\w+)';
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 ##

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

396# 'function', 'struct', 'union', 'enum', 'typedef'
397my $decl_type;
398
399my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
400my $doc_end = '\*/';
401my $doc_com = '\s*\*\s*';
402my $doc_com_body = '\s*\* ?';
403my $doc_decl = $doc_com . '(\w+)';
404my $doc_sect = $doc_com . '(\@?[\w\s]+):(.*)';
404# @params and a strictly limited set of supported section names
405my $doc_sect = $doc_com . '\s*(\@\w+|description|context|returns?)\s*:(.*)';
405my $doc_content = $doc_com_body . '(.*)';
406my $doc_block = $doc_com . 'DOC:\s*(.*)?';
407my $doc_inline_start = '^\s*/\*\*\s*$';
408my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
409my $doc_inline_end = '^\s*\*/\s*$';
410my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
411
412my %parameterdescs;
413my @parameterlist;
414my %sections;
415my @sectionlist;
416my $sectcheck;
417my $struct_actual;
418
419my $contents = "";
406my $doc_content = $doc_com_body . '(.*)';
407my $doc_block = $doc_com . 'DOC:\s*(.*)?';
408my $doc_inline_start = '^\s*/\*\*\s*$';
409my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
410my $doc_inline_end = '^\s*\*/\s*$';
411my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
412
413my %parameterdescs;
414my @parameterlist;
415my %sections;
416my @sectionlist;
417my $sectcheck;
418my $struct_actual;
419
420my $contents = "";
421
422# the canonical section names. see also $doc_sect above.
420my $section_default = "Description"; # default section
421my $section_intro = "Introduction";
422my $section = $section_default;
423my $section_context = "Context";
424my $section_return = "Return";
425
426my $undescribed = "-- undescribed --";
427

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

2793 }
2794 } else {
2795 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2796 " - I thought it was a doc line\n";
2797 ++$warnings;
2798 $state = STATE_NORMAL;
2799 }
2800 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
423my $section_default = "Description"; # default section
424my $section_intro = "Introduction";
425my $section = $section_default;
426my $section_context = "Context";
427my $section_return = "Return";
428
429my $undescribed = "-- undescribed --";
430

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

2796 }
2797 } else {
2798 print STDERR "${file}:$.: warning: Cannot understand $_ on line $.",
2799 " - I thought it was a doc line\n";
2800 ++$warnings;
2801 $state = STATE_NORMAL;
2802 }
2803 } elsif ($state == STATE_FIELD) { # look for head: lines, and include content
2801 if (/$doc_sect/o) {
2804 if (/$doc_sect/i) { # case insensitive for supported section names
2802 $newsection = $1;
2803 $newcontents = $2;
2804
2805 $newsection = $1;
2806 $newcontents = $2;
2807
2808 # map the supported section names to the canonical names
2809 if ($newsection =~ m/^description$/i) {
2810 $newsection = $section_default;
2811 } elsif ($newsection =~ m/^context$/i) {
2812 $newsection = $section_context;
2813 } elsif ($newsection =~ m/^returns?$/i) {
2814 $newsection = $section_return;
2815 } elsif ($newsection =~ m/^\@return$/) {
2816 # special: @return is a section, not a param description
2817 $newsection = $section_return;
2818 }
2819
2805 if (($contents ne "") && ($contents ne "\n")) {
2806 if (!$in_doc_sect && $verbose) {
2807 print STDERR "${file}:$.: warning: contents before sections\n";
2808 ++$warnings;
2809 }
2810 dump_section($file, $section, xml_escape($contents));
2811 $section = $section_default;
2812 }

--- 229 unchanged lines hidden ---
2820 if (($contents ne "") && ($contents ne "\n")) {
2821 if (!$in_doc_sect && $verbose) {
2822 print STDERR "${file}:$.: warning: contents before sections\n";
2823 ++$warnings;
2824 }
2825 dump_section($file, $section, xml_escape($contents));
2826 $section = $section_default;
2827 }

--- 229 unchanged lines hidden ---