kernel-doc (508dc4f8eece1a70c493afc6511fdf5934fef567) kernel-doc (1b40c1944db445c1de1c47ffd8cd426167f488e8)
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 ##
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 ##
9## Copyright (C) 2012 Dan Luedtke ##
9## ##
10## #define enhancements by Armin Kuster <akuster@mvista.com> ##
11## Copyright (c) 2000 MontaVista Software, Inc. ##
12## ##
13## This software falls under the GNU General Public License. ##
14## Please read the COPYING file for more information ##
15
16# 18/01/2001 - Cleanups

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

30# Return error code.
31# Keith Owens <kaos@ocs.com.au>
32
33# 23/09/2001 - Added support for typedefs, structs, enums and unions
34# Support for Context section; can be terminated using empty line
35# Small fixes (like spaces vs. \s in regex)
36# -- Tim Jansen <tim@tjansen.de>
37
10## ##
11## #define enhancements by Armin Kuster <akuster@mvista.com> ##
12## Copyright (c) 2000 MontaVista Software, Inc. ##
13## ##
14## This software falls under the GNU General Public License. ##
15## Please read the COPYING file for more information ##
16
17# 18/01/2001 - Cleanups

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

31# Return error code.
32# Keith Owens <kaos@ocs.com.au>
33
34# 23/09/2001 - Added support for typedefs, structs, enums and unions
35# Support for Context section; can be terminated using empty line
36# Small fixes (like spaces vs. \s in regex)
37# -- Tim Jansen <tim@tjansen.de>
38
39# 25/07/2012 - Added support for HTML5
40# -- Dan Luedtke <mail@danrl.de>
38
39#
40# This will read a 'c' file and scan for embedded comments in the
41# style of gnome comments (+minor extensions - see below).
42#
43
44# Note: This only supports 'c'.
45
46# usage:
41
42#
43# This will read a 'c' file and scan for embedded comments in the
44# style of gnome comments (+minor extensions - see below).
45#
46
47# Note: This only supports 'c'.
48
49# usage:
47# kernel-doc [ -docbook | -html | -text | -man | -list ] [ -no-doc-sections ]
48# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile
50# kernel-doc [ -docbook | -html | -html5 | -text | -man | -list ]
51# [ -no-doc-sections ]
52# [ -function funcname [ -function funcname ...] ]
53# c file(s)s > outputfile
49# or
54# or
50# [ -nofunction funcname [ -function funcname ...] ] c file(s)s > outputfile
55# [ -nofunction funcname [ -function funcname ...] ]
56# c file(s)s > outputfile
51#
57#
52# Set output format using one of -docbook -html -text or -man. Default is man.
58# Set output format using one of -docbook -html -html5 -text or -man.
59# Default is man.
53# The -list format is for internal use by docproc.
54#
55# -no-doc-sections
56# Do not output DOC: sections
57#
58# -function funcname
59# If set, then only generate documentation for the given function(s) or
60# DOC: section titles. All other functions and DOC: sections are ignored.

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

177 $type_func, "<b>\$1</b>",
178 $type_struct_xml, "<i>\$1</i>",
179 $type_env, "<b><i>\$1</i></b>",
180 $type_param, "<tt><b>\$1</b></tt>" );
181my $local_lt = "\\\\\\\\lt:";
182my $local_gt = "\\\\\\\\gt:";
183my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
184
60# The -list format is for internal use by docproc.
61#
62# -no-doc-sections
63# Do not output DOC: sections
64#
65# -function funcname
66# If set, then only generate documentation for the given function(s) or
67# DOC: section titles. All other functions and DOC: sections are ignored.

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

184 $type_func, "<b>\$1</b>",
185 $type_struct_xml, "<i>\$1</i>",
186 $type_env, "<b><i>\$1</i></b>",
187 $type_param, "<tt><b>\$1</b></tt>" );
188my $local_lt = "\\\\\\\\lt:";
189my $local_gt = "\\\\\\\\gt:";
190my $blankline_html = $local_lt . "p" . $local_gt; # was "<p>"
191
192# html version 5
193my %highlights_html5 = ( $type_constant, "<span class=\"const\">\$1</span>",
194 $type_func, "<span class=\"func\">\$1</span>",
195 $type_struct_xml, "<span class=\"struct\">\$1</span>",
196 $type_env, "<span class=\"env\">\$1</span>",
197 $type_param, "<span class=\"param\">\$1</span>" );
198my $blankline_html5 = $local_lt . "br /" . $local_gt;
199
185# XML, docbook format
186my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
187 $type_constant, "<constant>\$1</constant>",
188 $type_func, "<function>\$1</function>",
189 $type_struct_xml, "<structname>\$1</structname>",
190 $type_env, "<envar>\$1</envar>",
191 $type_param, "<parameter>\$1</parameter>" );
192my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";

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

304reset_state();
305
306while ($ARGV[0] =~ m/^-(.*)/) {
307 my $cmd = shift @ARGV;
308 if ($cmd eq "-html") {
309 $output_mode = "html";
310 %highlights = %highlights_html;
311 $blankline = $blankline_html;
200# XML, docbook format
201my %highlights_xml = ( "([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>",
202 $type_constant, "<constant>\$1</constant>",
203 $type_func, "<function>\$1</function>",
204 $type_struct_xml, "<structname>\$1</structname>",
205 $type_env, "<envar>\$1</envar>",
206 $type_param, "<parameter>\$1</parameter>" );
207my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";

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

319reset_state();
320
321while ($ARGV[0] =~ m/^-(.*)/) {
322 my $cmd = shift @ARGV;
323 if ($cmd eq "-html") {
324 $output_mode = "html";
325 %highlights = %highlights_html;
326 $blankline = $blankline_html;
327 } elsif ($cmd eq "-html5") {
328 $output_mode = "html5";
329 %highlights = %highlights_html5;
330 $blankline = $blankline_html5;
312 } elsif ($cmd eq "-man") {
313 $output_mode = "man";
314 %highlights = %highlights_man;
315 $blankline = $blankline_man;
316 } elsif ($cmd eq "-text") {
317 $output_mode = "text";
318 %highlights = %highlights_text;
319 $blankline = $blankline_text;

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

346 } elsif ($cmd eq '-no-doc-sections') {
347 $no_doc_sections = 1;
348 }
349}
350
351# continue execution near EOF;
352
353sub usage {
331 } elsif ($cmd eq "-man") {
332 $output_mode = "man";
333 %highlights = %highlights_man;
334 $blankline = $blankline_man;
335 } elsif ($cmd eq "-text") {
336 $output_mode = "text";
337 %highlights = %highlights_text;
338 $blankline = $blankline_text;

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

365 } elsif ($cmd eq '-no-doc-sections') {
366 $no_doc_sections = 1;
367 }
368}
369
370# continue execution near EOF;
371
372sub usage {
354 print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -list ]\n";
373 print "Usage: $0 [ -docbook | -html | -html5 | -text | -man | -list ]\n";
355 print " [ -no-doc-sections ]\n";
356 print " [ -function funcname [ -function funcname ...] ]\n";
357 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
374 print " [ -no-doc-sections ]\n";
375 print " [ -function funcname [ -function funcname ...] ]\n";
376 print " [ -nofunction funcname [ -nofunction funcname ...] ]\n";
377 print " [ -v ]\n";
358 print " c source file(s) > outputfile\n";
359 print " -v : verbose output, more warnings & other info listed\n";
360 exit 1;
361}
362
363# get kernel version from env
364sub get_kernel_version() {
365 my $version = 'unknown kernel version';

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

443 my $line;
444
445# DEBUG
446# if (!defined $contents) {
447# use Carp;
448# confess "output_highlight got called with no args?\n";
449# }
450
378 print " c source file(s) > outputfile\n";
379 print " -v : verbose output, more warnings & other info listed\n";
380 exit 1;
381}
382
383# get kernel version from env
384sub get_kernel_version() {
385 my $version = 'unknown kernel version';

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

463 my $line;
464
465# DEBUG
466# if (!defined $contents) {
467# use Carp;
468# confess "output_highlight got called with no args?\n";
469# }
470
451 if ($output_mode eq "html" || $output_mode eq "xml") {
471 if ($output_mode eq "html" || $output_mode eq "html5" ||
472 $output_mode eq "xml") {
452 $contents = local_unescape($contents);
453 # convert data read & converted thru xml_escape() into &xyz; format:
454 $contents =~ s/\\\\\\/\&/g;
455 }
456# print STDERR "contents b4:$contents\n";
457 eval $dohighlight;
458 die $@ if $@;
459# print STDERR "contents af:$contents\n";
460
473 $contents = local_unescape($contents);
474 # convert data read & converted thru xml_escape() into &xyz; format:
475 $contents =~ s/\\\\\\/\&/g;
476 }
477# print STDERR "contents b4:$contents\n";
478 eval $dohighlight;
479 die $@ if $@;
480# print STDERR "contents af:$contents\n";
481
482# strip whitespaces when generating html5
483 if ($output_mode eq "html5") {
484 $contents =~ s/^\s+//;
485 $contents =~ s/\s+$//;
486 }
461 foreach $line (split "\n", $contents) {
462 if ($line eq ""){
463 print $lineprefix, local_unescape($blankline);
464 } else {
465 $line =~ s/\\\\\\/\&/g;
466 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
467 print "\\&$line";
468 } else {
469 print $lineprefix, $line;
470 }
471 }
472 print "\n";
473 }
474}
475
487 foreach $line (split "\n", $contents) {
488 if ($line eq ""){
489 print $lineprefix, local_unescape($blankline);
490 } else {
491 $line =~ s/\\\\\\/\&/g;
492 if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
493 print "\\&$line";
494 } else {
495 print $lineprefix, $line;
496 }
497 }
498 print "\n";
499 }
500}
501
476#output sections in html
502# output sections in html
477sub output_section_html(%) {
478 my %args = %{$_[0]};
479 my $section;
480
481 foreach $section (@{$args{'sectionlist'}}) {
482 print "<h3>$section</h3>\n";
483 print "<blockquote>\n";
484 output_highlight($args{'sections'}{$section});

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

628 print "<h3>$section</h3>\n";
629 print "<ul>\n";
630 output_highlight($args{'sections'}{$section});
631 print "</ul>\n";
632 }
633 print "<hr>\n";
634}
635
503sub output_section_html(%) {
504 my %args = %{$_[0]};
505 my $section;
506
507 foreach $section (@{$args{'sectionlist'}}) {
508 print "<h3>$section</h3>\n";
509 print "<blockquote>\n";
510 output_highlight($args{'sections'}{$section});

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

654 print "<h3>$section</h3>\n";
655 print "<ul>\n";
656 output_highlight($args{'sections'}{$section});
657 print "</ul>\n";
658 }
659 print "<hr>\n";
660}
661
662# output sections in html5
663sub output_section_html5(%) {
664 my %args = %{$_[0]};
665 my $section;
666
667 foreach $section (@{$args{'sectionlist'}}) {
668 print "<section>\n";
669 print "<h1>$section</h1>\n";
670 print "<p>\n";
671 output_highlight($args{'sections'}{$section});
672 print "</p>\n";
673 print "</section>\n";
674 }
675}
676
677# output enum in html5
678sub output_enum_html5(%) {
679 my %args = %{$_[0]};
680 my ($parameter);
681 my $count;
682 my $html5id;
683
684 $html5id = $args{'enum'};
685 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
686 print "<article class=\"enum\" id=\"enum:". $html5id . "\">";
687 print "<h1>enum " . $args{'enum'} . "</h1>\n";
688 print "<ol class=\"code\">\n";
689 print "<li>";
690 print "<span class=\"keyword\">enum</span> ";
691 print "<span class=\"identifier\">" . $args{'enum'} . "</span> {";
692 print "</li>\n";
693 $count = 0;
694 foreach $parameter (@{$args{'parameterlist'}}) {
695 print "<li class=\"indent\">";
696 print "<span class=\"param\">" . $parameter . "</span>";
697 if ($count != $#{$args{'parameterlist'}}) {
698 $count++;
699 print ",";
700 }
701 print "</li>\n";
702 }
703 print "<li>};</li>\n";
704 print "</ol>\n";
705
706 print "<section>\n";
707 print "<h1>Constants</h1>\n";
708 print "<dl>\n";
709 foreach $parameter (@{$args{'parameterlist'}}) {
710 print "<dt>" . $parameter . "</dt>\n";
711 print "<dd>";
712 output_highlight($args{'parameterdescs'}{$parameter});
713 print "</dd>\n";
714 }
715 print "</dl>\n";
716 print "</section>\n";
717 output_section_html5(@_);
718 print "</article>\n";
719}
720
721# output typedef in html5
722sub output_typedef_html5(%) {
723 my %args = %{$_[0]};
724 my ($parameter);
725 my $count;
726 my $html5id;
727
728 $html5id = $args{'typedef'};
729 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
730 print "<article class=\"typedef\" id=\"typedef:" . $html5id . "\">\n";
731 print "<h1>typedef " . $args{'typedef'} . "</h1>\n";
732
733 print "<ol class=\"code\">\n";
734 print "<li>";
735 print "<span class=\"keyword\">typedef</span> ";
736 print "<span class=\"identifier\">" . $args{'typedef'} . "</span>";
737 print "</li>\n";
738 print "</ol>\n";
739 output_section_html5(@_);
740 print "</article>\n";
741}
742
743# output struct in html5
744sub output_struct_html5(%) {
745 my %args = %{$_[0]};
746 my ($parameter);
747 my $html5id;
748
749 $html5id = $args{'struct'};
750 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
751 print "<article class=\"struct\" id=\"struct:" . $html5id . "\">\n";
752 print "<hgroup>\n";
753 print "<h1>" . $args{'type'} . " " . $args{'struct'} . "</h1>";
754 print "<h2>". $args{'purpose'} . "</h2>\n";
755 print "</hgroup>\n";
756 print "<ol class=\"code\">\n";
757 print "<li>";
758 print "<span class=\"type\">" . $args{'type'} . "</span> ";
759 print "<span class=\"identifier\">" . $args{'struct'} . "</span> {";
760 print "</li>\n";
761 foreach $parameter (@{$args{'parameterlist'}}) {
762 print "<li class=\"indent\">";
763 if ($parameter =~ /^#/) {
764 print "<span class=\"param\">" . $parameter ."</span>\n";
765 print "</li>\n";
766 next;
767 }
768 my $parameter_name = $parameter;
769 $parameter_name =~ s/\[.*//;
770
771 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
772 $type = $args{'parametertypes'}{$parameter};
773 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
774 # pointer-to-function
775 print "<span class=\"type\">$1</span> ";
776 print "<span class=\"param\">$parameter</span>";
777 print "<span class=\"type\">)</span> ";
778 print "(<span class=\"args\">$2</span>);";
779 } elsif ($type =~ m/^(.*?)\s*(:.*)/) {
780 # bitfield
781 print "<span class=\"type\">$1</span> ";
782 print "<span class=\"param\">$parameter</span>";
783 print "<span class=\"bits\">$2</span>;";
784 } else {
785 print "<span class=\"type\">$type</span> ";
786 print "<span class=\"param\">$parameter</span>;";
787 }
788 print "</li>\n";
789 }
790 print "<li>};</li>\n";
791 print "</ol>\n";
792
793 print "<section>\n";
794 print "<h1>Members</h1>\n";
795 print "<dl>\n";
796 foreach $parameter (@{$args{'parameterlist'}}) {
797 ($parameter =~ /^#/) && next;
798
799 my $parameter_name = $parameter;
800 $parameter_name =~ s/\[.*//;
801
802 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
803 print "<dt>" . $parameter . "</dt>\n";
804 print "<dd>";
805 output_highlight($args{'parameterdescs'}{$parameter_name});
806 print "</dd>\n";
807 }
808 print "</dl>\n";
809 print "</section>\n";
810 output_section_html5(@_);
811 print "</article>\n";
812}
813
814# output function in html5
815sub output_function_html5(%) {
816 my %args = %{$_[0]};
817 my ($parameter, $section);
818 my $count;
819 my $html5id;
820
821 $html5id = $args{'function'};
822 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
823 print "<article class=\"function\" id=\"func:". $html5id . "\">\n";
824 print "<hgroup>\n";
825 print "<h1>" . $args{'function'} . "</h1>";
826 print "<h2>" . $args{'purpose'} . "</h2>\n";
827 print "</hgroup>\n";
828 print "<ol class=\"code\">\n";
829 print "<li>";
830 print "<span class=\"type\">" . $args{'functiontype'} . "</span> ";
831 print "<span class=\"identifier\">" . $args{'function'} . "</span> (";
832 print "</li>";
833 $count = 0;
834 foreach $parameter (@{$args{'parameterlist'}}) {
835 print "<li class=\"indent\">";
836 $type = $args{'parametertypes'}{$parameter};
837 if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
838 # pointer-to-function
839 print "<span class=\"type\">$1</span> ";
840 print "<span class=\"param\">$parameter</span>";
841 print "<span class=\"type\">)</span> ";
842 print "(<span class=\"args\">$2</span>)";
843 } else {
844 print "<span class=\"type\">$type</span> ";
845 print "<span class=\"param\">$parameter</span>";
846 }
847 if ($count != $#{$args{'parameterlist'}}) {
848 $count++;
849 print ",";
850 }
851 print "</li>\n";
852 }
853 print "<li>)</li>\n";
854 print "</ol>\n";
855
856 print "<section>\n";
857 print "<h1>Arguments</h1>\n";
858 print "<p>\n";
859 print "<dl>\n";
860 foreach $parameter (@{$args{'parameterlist'}}) {
861 my $parameter_name = $parameter;
862 $parameter_name =~ s/\[.*//;
863
864 ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
865 print "<dt>" . $parameter . "</dt>\n";
866 print "<dd>";
867 output_highlight($args{'parameterdescs'}{$parameter_name});
868 print "</dd>\n";
869 }
870 print "</dl>\n";
871 print "</section>\n";
872 output_section_html5(@_);
873 print "</article>\n";
874}
875
876# output DOC: block header in html5
877sub output_blockhead_html5(%) {
878 my %args = %{$_[0]};
879 my ($parameter, $section);
880 my $count;
881 my $html5id;
882
883 foreach $section (@{$args{'sectionlist'}}) {
884 $html5id = $section;
885 $html5id =~ s/[^a-zA-Z0-9\-]+/_/g;
886 print "<article class=\"doc\" id=\"doc:". $html5id . "\">\n";
887 print "<h1>$section</h1>\n";
888 print "<p>\n";
889 output_highlight($args{'sections'}{$section});
890 print "</p>\n";
891 }
892 print "</article>\n";
893}
894
636sub output_section_xml(%) {
637 my %args = %{$_[0]};
638 my $section;
639 # print out each section
640 $lineprefix=" ";
641 foreach $section (@{$args{'sectionlist'}}) {
642 print "<refsect1>\n";
643 print "<title>$section</title>\n";

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

1781 $prototype =~ s/^__inline__ +//;
1782 $prototype =~ s/^__inline +//;
1783 $prototype =~ s/^__always_inline +//;
1784 $prototype =~ s/^noinline +//;
1785 $prototype =~ s/__devinit +//;
1786 $prototype =~ s/__init +//;
1787 $prototype =~ s/__init_or_module +//;
1788 $prototype =~ s/__must_check +//;
895sub output_section_xml(%) {
896 my %args = %{$_[0]};
897 my $section;
898 # print out each section
899 $lineprefix=" ";
900 foreach $section (@{$args{'sectionlist'}}) {
901 print "<refsect1>\n";
902 print "<title>$section</title>\n";

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

2040 $prototype =~ s/^__inline__ +//;
2041 $prototype =~ s/^__inline +//;
2042 $prototype =~ s/^__always_inline +//;
2043 $prototype =~ s/^noinline +//;
2044 $prototype =~ s/__devinit +//;
2045 $prototype =~ s/__init +//;
2046 $prototype =~ s/__init_or_module +//;
2047 $prototype =~ s/__must_check +//;
1789 $prototype =~ s/__weak +//;
1790 $prototype =~ s/^#\s*define\s+//; #ak added
1791 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
1792
1793 # Yes, this truly is vile. We are looking for:
1794 # 1. Return type (may be nothing if we're looking at a macro)
1795 # 2. Function name
1796 # 3. Function parameters.
1797 #

--- 498 unchanged lines hidden --- 		2048 $prototype =~ s/^#\s*define\s+//; #ak added
2049 $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
2050
2051 # Yes, this truly is vile. We are looking for:
2052 # 1. Return type (may be nothing if we're looking at a macro)
2053 # 2. Function name
2054 # 3. Function parameters.
2055 #

--- 498 unchanged lines hidden ---