History

Merge tag 'docs-for-linus' of git://git.lwn.net/linux-2.6

Pull documentation updates from Jonathan Corbet: "There's been a fair amount going on in the docs tree this time around, including: - Support for reproducible document builds, from Ben Hutchings and company. - The ability to automatically generate cross-reference links within a single DocBook book and embedded descriptions for large structures. From Danilo Cesar Lemes de Paula. - A new document on how to add a system call from David Drysdale. - Chameleon bus documentation from Johannes Thumshirn. ...plus the usual collection of improvements, typo fixes, and more" * tag 'docs-for-linus' of git://git.lwn.net/linux-2.6: (39 commits) Documentation, add kernel-parameters.txt entry for dis_ucode_ldr Documentation/x86: Rename IRQSTACKSIZE to IRQ_STACK_SIZE Documentation/Intel-IOMMU.txt: Modify definition of DRHD docs: update HOWTO for 3.x -> 4.x versioning kernel-doc: ignore unneeded attribute information scripts/kernel-doc: Adding cross-reference links to html documentation. DocBook: Fix non-determinstic installation of duplicate man pages Documentation: minor typo fix in mailbox.txt Documentation: describe how to add a system call doc: Add more workqueue functions to the documentation ARM: keystone: add documentation for SoCs and EVMs scripts/kernel-doc Allow struct arguments documentation in struct body SubmittingPatches: remove stray quote character Revert "DocBook: Avoid building man pages repeatedly and inconsistently" Documentation: Minor changes to men-chameleon-bus.txt Doc: fix trivial typo in SubmittingPatches MAINTAINERS: Direct Documentation/DocBook/media properly Documentation: installed man pages don't need to be executable fix Evolution submenu name in email-clients.txt Documentation: Add MCB documentation ...

Linus Torvalds committed 11 years ago

Commit e2701602 parents 22629b6 ce14c5828 files · +1195 −76Browse files

Showing the changes to scripts (2 of 28 files). Show all

Unified · Split

2 files
  1. scripts/kernel-doc +90 −6
  2. scripts/kernel-doc-xml-ref +198 −0
scripts/kernel-doc+90−6
@@ -133,6 +133,30 @@ use strict; · 132 unmodified lines
133133 #
134134 # All descriptions can be multiline, except the short function description.
135135 #
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+#
136160 # You can also add additional sections. When documenting kernel functions you
137161 # should document the "Context:" of the function, e.g. whether the functions
138162 # can be called form interrupts. Unlike other sections you can end it with an
@@ -253,11 +277,20 @@ my %highlights = %highlights_man; · 114 unmodified lines
253277 my $blankline = $blankline_man;
254278 my $modulename = "Kernel API";
255279 my $function_only = 0;
280+my $show_not_found = 0;
281+
282+my @build_time;
283+if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&
284+ (my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {
285+ @build_time = gmtime($seconds);
286+} else {
287+ @build_time = localtime;
288+}
289+
256290 my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',
257291 'July', 'August', 'September', 'October',
258− 'November', 'December')[(localtime)[4]] .
259− " " . ((localtime)[5]+1900);
260−my $show_not_found = 0;
292+ 'November', 'December')[$build_time[4]] .
293+ " " . ($build_time[5]+1900);
261294
262295 # Essentially these are globals.
263296 # They probably want to be tidied up, made more localised or something.
@@ -287,9 +320,19 @@ my $lineprefix=""; · 23 unmodified lines
287320 # 2 - scanning field start.
288321 # 3 - scanning prototype.
289322 # 4 - documentation block
323+# 5 - gathering documentation outside main block
290324 my $state;
291325 my $in_doc_sect;
292326
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.
334+my $split_doc_state;
335+
293336 #declaration types: can be
294337 # 'function', 'struct', 'union', 'enum', 'typedef'
295338 my $decl_type;
@@ -304,6 +347,9 @@ my $doc_decl = $doc_com . '(\w+)'; · 8 unmodified lines
304347 my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)';
305348 my $doc_content = $doc_com_body . '(.*)';
306349 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
350+my $doc_split_start = '^\s*/\*\*\s*$';
351+my $doc_split_sect = '\s*\*\s*(@[\w\s]+):(.*)';
352+my $doc_split_end = '^\s*\*/\s*$';
307353
308354 my %constants;
309355 my %parameterdescs;
@@ -1753,7 +1799,9 @@ sub dump_struct($$) { · 1443 unmodified lines
17531799 # strip kmemcheck_bitfield_{begin,end}.*;
17541800 $members =~ s/kmemcheck_bitfield_.*?;//gos;
17551801 # strip attributes
1802+ $members =~ s/__attribute__\s*\(\([a-z,_\*\s\(\)]*\)\)//i;
17561803 $members =~ s/__aligned\s*\([^;]*\)//gos;
1804+ $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos;
17571805
17581806 create_parameterlist($members, ';', $file);
17591807 check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested);
@@ -2181,6 +2229,7 @@ sub reset_state { · 421 unmodified lines
21812229 $prototype = "";
21822230
21832231 $state = 0;
2232+ $split_doc_state = 0;
21842233 }
21852234
21862235 sub tracepoint_munge($) {
@@ -2453,7 +2502,6 @@ sub process_file($) { · 266 unmodified lines
24532502 }
24542503 $section = $newsection;
24552504 } elsif (/$doc_end/) {
2456−
24572505 if (($contents ne "") && ($contents ne "\n")) {
24582506 dump_section($file, $section, xml_escape($contents));
24592507 $section = $section_default;
@@ -2494,8 +2542,44 @@ sub process_file($) { · 34 unmodified lines
24942542 print STDERR "Warning(${file}:$.): bad line: $_";
24952543 ++$warnings;
24962544 }
2545+ } elsif ($state == 5) { # scanning for split parameters
2546+ # First line (state 1) needs to be a @parameter
2547+ if ($split_doc_state == 1 && /$doc_split_sect/o) {
2548+ $section = $1;
2549+ $contents = $2;
2550+ if ($contents ne "") {
2551+ while ((substr($contents, 0, 1) eq " ") ||
2552+ substr($contents, 0, 1) eq "\t") {
2553+ $contents = substr($contents, 1);
2554+ }
2555+ $contents .= "\n";
2556+ }
2557+ $split_doc_state = 2;
2558+ # Documentation block end */
2559+ } elsif (/$doc_split_end/) {
2560+ if (($contents ne "") && ($contents ne "\n")) {
2561+ dump_section($file, $section, xml_escape($contents));
2562+ $section = $section_default;
2563+ $contents = "";
2564+ }
2565+ $state = 3;
2566+ $split_doc_state = 0;
2567+ # Regular text
2568+ } elsif (/$doc_content/) {
2569+ if ($split_doc_state == 2) {
2570+ $contents .= $1 . "\n";
2571+ } elsif ($split_doc_state == 1) {
2572+ $split_doc_state = 4;
2573+ print STDERR "Warning(${file}:$.): ";
2574+ print STDERR "Incorrect use of kernel-doc format: $_";
2575+ ++$warnings;
2576+ }
2577+ }
24972578 } elsif ($state == 3) { # scanning for function '{' (end of prototype)
2498− if ($decl_type eq 'function') {
2579+ if (/$doc_split_start/) {
2580+ $state = 5;
2581+ $split_doc_state = 1;
2582+ } elsif ($decl_type eq 'function') {
24992583 process_state3_function($_, $file);
25002584 } else {
25012585 process_state3_type($_, $file);
@@ -2587,7 +2671,7 @@ $kernelversion = get_kernel_version(); · 85 unmodified lines
25872671
25882672 # generate a sequence of code that will splice in highlighting information
25892673 # using the s// operator.
2590−foreach my $pattern (keys %highlights) {
2674+foreach my $pattern (sort keys %highlights) {
25912675 # print STDERR "scanning pattern:$pattern, highlight:($highlights{$pattern})\n";
25922676 $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n";
25932677 }
scripts/kernel-doc-xml-ref+198−0
@@ -0,0 +1,198 @@
1+#!/usr/bin/perl -w
2+
3+use strict;
4+
5+## Copyright (C) 2015 Intel Corporation ##
6+# ##
7+## This software falls under the GNU General Public License. ##
8+## Please read the COPYING file for more information ##
9+#
10+#
11+# This software reads a XML file and a list of valid interal
12+# references to replace Docbook tags with links.
13+#
14+# The list of "valid internal references" must be one-per-line in the following format:
15+# API-struct-foo
16+# API-enum-bar
17+# API-my-function
18+#
19+# The software walks over the XML file looking for xml tags representing possible references
20+# to the Document. Each reference will be cross checked against the "Valid Internal Reference" list. If
21+# the referece is found it replaces its content by a <link> tag.
22+#
23+# usage:
24+# kernel-doc-xml-ref -db filename
25+# xml filename > outputfile
26+
27+# read arguments
28+if ($#ARGV != 2) {
29+ usage();
30+}
31+
32+#Holds the database filename
33+my $databasefile;
34+my @database;
35+
36+#holds the inputfile
37+my $inputfile;
38+my $errors = 0;
39+
40+my %highlights = (
41+ "<function>(.*?)</function>",
42+ "\"<function>\" . convert_function(\$1, \$line) . \"</function>\"",
43+ "<structname>(.*?)</structname>",
44+ "\"<structname>\" . convert_struct(\$1) . \"</structname>\"",
45+ "<funcdef>(.*?)<function>(.*?)</function></funcdef>",
46+ "\"<funcdef>\" . convert_param(\$1) . \"<function>\$2</function></funcdef>\"",
47+ "<paramdef>(.*?)<parameter>(.*?)</parameter></paramdef>",
48+ "\"<paramdef>\" . convert_param(\$1) . \"<parameter>\$2</parameter></paramdef>\"");
49+
50+while($ARGV[0] =~ m/^-(.*)/) {
51+ my $cmd = shift @ARGV;
52+ if ($cmd eq "-db") {
53+ $databasefile = shift @ARGV
54+ } else {
55+ usage();
56+ }
57+}
58+$inputfile = shift @ARGV;
59+
60+sub open_database {
61+ open (my $handle, '<', $databasefile) or die "Cannot open $databasefile";
62+ chomp(my @lines = <$handle>);
63+ close $handle;
64+
65+ @database = @lines;
66+}
67+
68+sub process_file {
69+ open_database();
70+
71+ my $dohighlight;
72+ foreach my $pattern (keys %highlights) {
73+ $dohighlight .= "\$line =~ s:$pattern:$highlights{$pattern}:eg;\n";
74+ }
75+
76+ open(FILE, $inputfile) or die("Could not open $inputfile") or die ("Cannot open $inputfile");
77+ foreach my $line (<FILE>) {
78+ eval $dohighlight;
79+ print $line;
80+ }
81+}
82+
83+sub trim($_)
84+{
85+ my $str = $_[0];
86+ $str =~ s/^\s+|\s+$//g;
87+ return $str
88+}
89+
90+sub has_key_defined($_)
91+{
92+ if ( grep( /^$_[0]$/, @database)) {
93+ return 1;
94+ }
95+ return 0;
96+}
97+
98+# Gets a <function> content and add it a hyperlink if possible.
99+sub convert_function($_)
100+{
101+ my $arg = $_[0];
102+ my $key = $_[0];
103+
104+ my $line = $_[1];
105+
106+ $key = trim($key);
107+
108+ $key =~ s/[^A-Za-z0-9]/-/g;
109+ $key = "API-" . $key;
110+
111+ # We shouldn't add links to <funcdef> prototype
112+ if (!has_key_defined($key) || $line =~ m/\s+<funcdef/i) {
113+ return $arg;
114+ }
115+
116+ my $head = $arg;
117+ my $tail = "";
118+ if ($arg =~ /(.*?)( ?)$/) {
119+ $head = $1;
120+ $tail = $2;
121+ }
122+ return "<link linkend=\"$key\">$head</link>$tail";
123+}
124+
125+# Converting a struct text to link
126+sub convert_struct($_)
127+{
128+ my $arg = $_[0];
129+ my $key = $_[0];
130+ $key =~ s/(struct )?(\w)/$2/g;
131+ $key =~ s/[^A-Za-z0-9]/-/g;
132+ $key = "API-struct-" . $key;
133+
134+ if (!has_key_defined($key)) {
135+ return $arg;
136+ }
137+
138+ my ($head, $tail) = split_pointer($arg);
139+ return "<link linkend=\"$key\">$head</link>$tail";
140+}
141+
142+# Identify "object *" elements
143+sub split_pointer($_)
144+{
145+ my $arg = $_[0];
146+ if ($arg =~ /(.*?)( ?\* ?)/) {
147+ return ($1, $2);
148+ }
149+ return ($arg, "");
150+}
151+
152+sub convert_param($_)
153+{
154+ my $type = $_[0];
155+ my $keyname = convert_key_name($type);
156+
157+ if (!has_key_defined($keyname)) {
158+ return $type;
159+ }
160+
161+ my ($head, $tail) = split_pointer($type);
162+ return "<link linkend=\"$keyname\">$head</link>$tail";
163+
164+}
165+
166+# DocBook links are in the API-<TYPE>-<STRUCT-NAME> format
167+# This method gets an element and returns a valid DocBook reference for it.
168+sub convert_key_name($_)
169+{
170+ #Pattern $2 is optional and might be uninitialized
171+ no warnings 'uninitialized';
172+
173+ my $str = $_[0];
174+ $str =~ s/(const|static)? ?(struct)? ?([a-zA-Z0-9_]+) ?(\*|&)?/$2 $3/g ;
175+
176+ # trim
177+ $str =~ s/^\s+|\s+$//g;
178+
179+ # spaces and _ to -
180+ $str =~ s/[^A-Za-z0-9]/-/g;
181+
182+ return "API-" . $str;
183+}
184+
185+sub usage {
186+ print "Usage: $0 -db database filename\n";
187+ print " xml source file(s) > outputfile\n";
188+ exit 1;
189+}
190+
191+# starting point
192+process_file();
193+
194+if ($errors) {
195+ print STDERR "$errors errors\n";
196+}
197+
198+exit($errors);