aboutsummaryrefslogtreecommitdiffstats
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc335
1 files changed, 12 insertions, 323 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f565536a2be..d793001929c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -5,8 +5,7 @@ use strict;
5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## 5## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ## 6## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##
7## Copyright (C) 2001 Simon Huggins ## 7## Copyright (C) 2001 Simon Huggins ##
8## Copyright (C) 2005-2012 Randy Dunlap ## 8## Copyright (C) 2005-2010 Randy Dunlap ##
9## Copyright (C) 2012 Dan Luedtke ##
10## ## 9## ##
11## #define enhancements by Armin Kuster <akuster@mvista.com> ## 10## #define enhancements by Armin Kuster <akuster@mvista.com> ##
12## Copyright (c) 2000 MontaVista Software, Inc. ## 11## Copyright (c) 2000 MontaVista Software, Inc. ##
@@ -36,8 +35,6 @@ use strict;
36# Small fixes (like spaces vs. \s in regex) 35# Small fixes (like spaces vs. \s in regex)
37# -- Tim Jansen <tim@tjansen.de> 36# -- Tim Jansen <tim@tjansen.de>
38 37
39# 25/07/2012 - Added support for HTML5
40# -- Dan Luedtke <mail@danrl.de>
41 38
42# 39#
43# This will read a 'c' file and scan for embedded comments in the 40# This will read a 'c' file and scan for embedded comments in the
@@ -47,16 +44,12 @@ use strict;
47# Note: This only supports 'c'. 44# Note: This only supports 'c'.
48 45
49# usage: 46# usage:
50# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ] 47# kernel-doc [ -docbook | -html | -text | -man | -list ] [ -no-doc-sections ]
51# [ -no-doc-sections ] 48# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
52# [ -function funcname [ -function funcname ...] ]
53# c file(s)s > outputfile
54# or 49# or
55# [ -nofunction funcname [ -function funcname ...] ] 50# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
56# c file(s)s > outputfile
57# 51#
58# Set output format using one of -docbook -html -html5 -text or -man. 52# Set output format using one of -docbook -html -text or -man. Default is man.
59# Default is man.
60# The -list format is for internal use by docproc. 53# The -list format is for internal use by docproc.
61# 54#
62# -no-doc-sections 55# -no-doc-sections
@@ -137,8 +130,6 @@ use strict;
137# should document the "Context:" of the function, e.g. whether the functions 130# 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 131# can be called form interrupts. Unlike other sections you can end it with an
139# empty line. 132# 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 133# Example-sections should contain the string EXAMPLE so that they are marked
143# appropriately in DocBook. 134# appropriately in DocBook.
144# 135#
@@ -191,14 +182,6 @@ my $local_lt = "\\\\\\\\lt:";
191my $local_gt = "\\\\\\\\gt:"; 182my $local_gt = "\\\\\\\\gt:";
192my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>" 183my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
193 184
194# html version 5
195my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
196 $type_func, "<span class=\"func\">\$1</span>",
197 $type_struct_xml, "<span class=\"struct\">\$1</span>",
198 $type_env, "<span class=\"env\">\$1</span>",
199 $type_param, "<span class=\"param\">\$1</span>" );
200my $blankline_html5 = $local_lt . "br /" . $local_gt;
201
202# XML, docbook format 185# XML, docbook format
203my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>", 186my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
204 $type_constant, "<constant>\$1</constant>", 187 $type_constant, "<constant>\$1</constant>",
@@ -247,7 +230,6 @@ my $dohighlight = "";
247 230
248my $verbose = 0; 231my $verbose = 0;
249my $output_mode = "man"; 232my $output_mode = "man";
250my $output_preformatted = 0;
251my $no_doc_sections = 0; 233my $no_doc_sections = 0;
252my %highlights = %highlights_man; 234my %highlights = %highlights_man;
253my $blankline = $blankline_man; 235my $blankline = $blankline_man;
@@ -298,10 +280,9 @@ my $doc_special = "\@\%\$\&";
298my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. 280my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
299my $doc_end = '\*/'; 281my $doc_end = '\*/';
300my $doc_com = '\s*\*\s*'; 282my $doc_com = '\s*\*\s*';
301my $doc_com_body = '\s*\* ?';
302my $doc_decl = $doc_com . '(\w+)'; 283my $doc_decl = $doc_com . '(\w+)';
303my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; 284my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
304my $doc_content = $doc_com_body . '(.*)'; 285my $doc_content = $doc_com . '(.*)';
305my $doc_block = $doc_com . 'DOC:\s*(.*)?'; 286my $doc_block = $doc_com . 'DOC:\s*(.*)?';
306 287
307my %constants; 288my %constants;
@@ -317,7 +298,6 @@ my $section_default = "Description"; # default section
317my $section_intro = "Introduction"; 298my $section_intro = "Introduction";
318my $section = $section_default; 299my $section = $section_default;
319my $section_context = "Context"; 300my $section_context = "Context";
320my $section_return = "Return";
321 301
322my $undescribed = "-- undescribed --"; 302my $undescribed = "-- undescribed --";
323 303
@@ -329,10 +309,6 @@ while ($ARGV[0] =~ m/^-(.*)/) {
329 $output_mode = "html"; 309 $output_mode = "html";
330 %highlights = %highlights_html; 310 %highlights = %highlights_html;
331 $blankline = $blankline_html; 311 $blankline = $blankline_html;
332 } elsif ($cmd eq "-html5") {
333 $output_mode = "html5";
334 %highlights = %highlights_html5;
335 $blankline = $blankline_html5;
336 } elsif ($cmd eq "-man") { 312 } elsif ($cmd eq "-man") {
337 $output_mode = "man"; 313 $output_mode = "man";
338 %highlights = %highlights_man; 314 %highlights = %highlights_man;
@@ -375,11 +351,10 @@ while ($ARGV[0] =~ m/^-(.*)/) {
375# continue execution near EOF; 351# continue execution near EOF;
376 352
377sub usage { 353sub usage {
378 print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n"; 354 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n";
379 print " [ -no-doc-sections ]\n"; 355 print " [ -no-doc-sections ]\n";
380 print " [ -function funcname [ -function funcname ...] ]\n"; 356 print " [ -function funcname [ -function funcname ...] ]\n";
381 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n"; 357 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
382 print " [ -v ]\n";
383 print " c source file(s) > outputfile\n"; 358 print " c source file(s) > outputfile\n";
384 print " -v : verbose output, more warnings & other info listed\n"; 359 print " -v : verbose output, more warnings & other info listed\n";
385 exit 1; 360 exit 1;
@@ -473,8 +448,7 @@ sub output_highlight {
473# confess "output_highlight got called with no args?\n"; 448# confess "output_highlight got called with no args?\n";
474# } 449# }
475 450
476 if ($output_mode eq "html" || $output_mode eq "html5" || 451 if ($output_mode eq "html" || $output_mode eq "xml") {
477 $output_mode eq "xml") {
478 $contents = local_unescape($contents); 452 $contents = local_unescape($contents);
479 # convert data read & converted thru xml_escape() into &xyz; format: 453 # convert data read & converted thru xml_escape() into &xyz; format:
480 $contents =~ s/\\\\\\/\&/g; 454 $contents =~ s/\\\\\\/\&/g;
@@ -484,19 +458,9 @@ sub output_highlight {
484 die $@ if $@; 458 die $@ if $@;
485# print STDERR "contents af:$contents\n"; 459# print STDERR "contents af:$contents\n";
486 460
487# strip whitespaces when generating html5
488 if ($output_mode eq "html5") {
489 $contents =~ s/^\s+//;
490 $contents =~ s/\s+$//;
491 }
492 foreach $line (split "\n", $contents) { 461 foreach $line (split "\n", $contents) {
493 if (! $output_preformatted) {
494 $line =~ s/^\s*//;
495 }
496 if ($line eq ""){ 462 if ($line eq ""){
497 if (! $output_preformatted) { 463 print $lineprefix, local_unescape($blankline);
498 print $lineprefix, local_unescape($blankline);
499 }
500 } else { 464 } else {
501 $line =~ s/\\\\\\/\&/g; 465 $line =~ s/\\\\\\/\&/g;
502 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { 466 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
@@ -509,7 +473,7 @@ sub output_highlight {
509 } 473 }
510} 474}
511 475
512# output sections in html 476#output sections in html
513sub output_section_html(%) { 477sub output_section_html(%) {
514 my %args = %{$_[0]}; 478 my %args = %{$_[0]};
515 my $section; 479 my $section;
@@ -669,239 +633,6 @@ sub output_blockhead_html(%) {
669 print "<hr>\n"; 633 print "<hr>\n";
670} 634}
671 635
672# output sections in html5
673sub output_section_html5(%) {
674 my %args = %{$_[0]};
675 my $section;
676
677 foreach $section (@{$args{'sectionlist'}}) {
678 print "<section>\n";
679 print "<h1>$section</h1>\n";
680 print "<p>\n";
681 output_highlight($args{'sections'}{$section});
682 print "</p>\n";
683 print "</section>\n";
684 }
685}
686
687# output enum in html5
688sub output_enum_html5(%) {
689 my %args = %{$_[0]};
690 my ($parameter);
691 my $count;
692 my $html5id;
693
694 $html5id = $args{'enum'};