From 5449bc94152a6c4700f46786be600141234d8f0f Mon Sep 17 00:00:00 2001 From: Pavel Pisa Date: Sat, 10 Feb 2007 01:45:37 -0800 Subject: [PATCH] DocBook/HTML: correction of recursive A tags in HTML output The malformed HTML was generated after switch to XSLTPROC from SGML tools. The reference title struct x is converted into two recursive tags struct x There is more possible solutions for this problem. One can be found at http://darkk.livejournal.com/ The proposed solution is based on suggestion provided by Jiri Kosek. Signed-off-by: Pavel Pisa Acked-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index f50a70f550b3..8a4ec43a4985 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -583,14 +583,14 @@ sub output_function_xml(%) { $id = "API-".$args{'function'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "\n"; + print "\n"; print "\n"; print " LINUX\n"; print " Kernel Hackers Manual\n"; print " $man_date\n"; print "\n"; print "\n"; - print " ".$args{'function'}."\n"; + print " ".$args{'function'}."\n"; print " 9\n"; print "\n"; print "\n"; @@ -659,14 +659,14 @@ sub output_struct_xml(%) { $id = "API-struct-".$args{'struct'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "\n"; + print "\n"; print "\n"; print " LINUX\n"; print " Kernel Hackers Manual\n"; print " $man_date\n"; print "\n"; print "\n"; - print " ".$args{'type'}." ".$args{'struct'}."\n"; + print " ".$args{'type'}." ".$args{'struct'}."\n"; print " 9\n"; print "\n"; print "\n"; @@ -743,14 +743,14 @@ sub output_enum_xml(%) { $id = "API-enum-".$args{'enum'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "\n"; + print "\n"; print "\n"; print " LINUX\n"; print " Kernel Hackers Manual\n"; print " $man_date\n"; print "\n"; print "\n"; - print " enum ".$args{'enum'}."\n"; + print " enum ".$args{'enum'}."\n"; print " 9\n"; print "\n"; print "\n"; @@ -809,14 +809,14 @@ sub output_typedef_xml(%) { $id = "API-typedef-".$args{'typedef'}; $id =~ s/[^A-Za-z0-9]/-/g; - print "\n"; + print "\n"; print "\n"; print " LINUX\n"; print " Kernel Hackers Manual\n"; print " $man_date\n"; print "\n"; print "\n"; - print " typedef ".$args{'typedef'}."\n"; + print " typedef ".$args{'typedef'}."\n"; print " 9\n"; print "\n"; print "\n"; -- cgit v1.2.3 From 891dcd2f7ab15e2aaad07f6925b3a53fd8d5c02f Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 10 Feb 2007 01:45:53 -0800 Subject: [PATCH] kernel-doc: allow a little whitespace In kernel-doc syntax, be a little flexible: allow whitespace between a function parameter name and the colon that must follow it, such as: @pdev : PCI device to unplug (This allows lots of megaraid kernel-doc to work without tons of editing.) Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/kernel-doc-nano-HOWTO.txt | 2 +- scripts/kernel-doc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 284e7e198e93..6ca507f40749 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -101,7 +101,7 @@ The format of the block comment is like this: /** * function_name(:)? (- short description)? -(* @parameterx: (description of parameter x)?)* +(* @parameterx(space)*: (description of parameter x)?)* (* a blank line)? * (Description:)? (Description of function)? * (section header: (section description)? )* diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8a4ec43a4985..35d7fd9a1e65 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -83,7 +83,7 @@ use strict; # * my_function # **/ # -# If the Description: header tag is ommitted, then there must be a blank line +# If the Description: header tag is omitted, then there must be a blank line # after the last parameter specification. # e.g. # /** @@ -265,7 +265,7 @@ my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start. my $doc_end = '\*/'; my $doc_com = '\s*\*\s*'; my $doc_decl = $doc_com.'(\w+)'; -my $doc_sect = $doc_com.'(['.$doc_special.']?[\w ]+):(.*)'; +my $doc_sect = $doc_com.'(['.$doc_special.']?[\w\s]+):(.*)'; my $doc_content = $doc_com.'(.*)'; my $doc_block = $doc_com.'DOC:\s*(.*)?'; -- cgit v1.2.3 From 996a07bcb62c5935248e238a1150089f3d99a6fb Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 10 Feb 2007 01:45:56 -0800 Subject: [PATCH] kernel-doc: allow more whitespace Allow whitespace in pointer-to-function [accept "(* done)", not just "(*done)"]. Allow tabs (spaces are already allowed) between "#define" and a macro name. Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 35d7fd9a1e65..cc63cd01d5ee 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1433,7 +1433,7 @@ sub create_parameterlist($$$) { } elsif ($arg =~ m/\(.*\*/) { # pointer-to-function $arg =~ tr/#/,/; - $arg =~ m/[^\(]+\(\*([^\)]+)\)/; + $arg =~ m/[^\(]+\(\*\s*([^\)]+)\)/; $param = $1; $type = $arg; $type =~ s/([^\(]+\(\*)$param/$1/; @@ -1536,7 +1536,7 @@ sub dump_function($$) { $prototype =~ s/^__always_inline +//; $prototype =~ s/^noinline +//; $prototype =~ s/__devinit +//; - $prototype =~ s/^#define +//; #ak added + $prototype =~ s/^#define\s+//; #ak added $prototype =~ s/__attribute__ \(\([a-z,]*\)\)//; # Yes, this truly is vile. We are looking for: -- cgit v1.2.3 From a21217daae8ce6e841e33d4a2bb24026723cb21d Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 10 Feb 2007 01:46:04 -0800 Subject: [PATCH] kernel-doc: fix some odd spacing issues - in man and text mode output, if the function return type is empty (like it is for macros), don't print the return type and a following space; this fixes an output malalignment; - in the function short description, strip leading, trailing, and multiple embedded spaces (to one space); this makes function name/description output spacing consistent; - fix a comment typo; Signed-off-by: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cc63cd01d5ee..c9b4d3631101 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -365,7 +365,7 @@ sub dump_section { # parameterlist => @list of parameters # parameterdescs => %parameter descriptions # sectionlist => @list of sections -# sections => %descriont descriptions +# sections => %section descriptions # sub output_highlight { @@ -953,7 +953,11 @@ sub output_function_man(%) { print $args{'function'}." \\- ".$args{'purpose'}."\n"; print ".SH SYNOPSIS\n"; - print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; + if ($args{'functiontype'} ne "") { + print ".B \"".$args{'functiontype'}."\" ".$args{'function'}."\n"; + } else { + print ".B \"".$args{'function'}."\n"; + } $count = 0; my $parenth = "("; my $post = ","; @@ -1118,13 +1122,19 @@ sub output_intro_man(%) { sub output_function_text(%) { my %args = %{$_[0]}; my ($parameter, $section); + my $start; print "Name:\n\n"; print $args{'function'}." - ".$args{'purpose'}."\n"; print "\nSynopsis:\n\n"; - my $start=$args{'functiontype'}." ".$args{'function'}." ("; + if ($args{'functiontype'} ne "") { + $start = $args{'functiontype'}." ".$args{'function'}." ("; + } else { + $start = $args{'function'}." ("; + } print $start; + my $count = 0; foreach my $parameter (@{$args{'parameterlist'}}) { $type = $args{'parametertypes'}{$parameter}; @@ -1710,6 +1720,7 @@ sub process_file($) { my $file; my $identifier; my $func; + my $descr; my $initial_section_counter = $section_counter; if (defined($ENV{'SRCTREE'})) { @@ -1753,7 +1764,12 @@ sub process_file($) { $state = 2; if (/-(.*)/) { - $declaration_purpose = xml_escape($1); + # strip leading/trailing/multiple spaces #RDD:T: + $descr= $1; + $descr =~ s/^\s*//; + $descr =~ s/\s*$//; + $descr =~ s/\s+/ /; + $declaration_purpose = xml_escape($descr); } else { $declaration_purpose = ""; } -- cgit v1.2.3 From 412ecd7751a2653ab17df39a1dc3565a548633fd Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Sat, 10 Feb 2007 22:47:33 -0800 Subject: [PATCH] fix fatal kernel-doc error Teach kernel-doc to handle functions that look like the new pcim_iomap_table(). Fixes this fatal error in scripts/kernel-doc: DOCPROC Documentation/DocBook/kernel-api.xml Error(/tester/linsrc/linux-2.6.20-git6//drivers/pci/pci.c:1351): cannot understand prototype: 'void __iomem * const * pcim_iomap_table(struct pci_dev *pdev) ' make[1]: *** [Documentation/DocBook/kernel-api.xml] Error 1 make: *** [htmldocs] Error 2 Signed-off-by: Randy Dunlap Signed-off-by: Linus Torvalds --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'scripts/kernel-doc') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c9b4d3631101..4d928b859845 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1580,7 +1580,8 @@ sub dump_function($$) { $prototype =~ m/^(\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || - $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { + $prototype =~ m/^(\w+\s+\w+\s+\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*\s*\w+\s*\*\s*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\{]*)\)/) { $return_type = $1; $declaration_name = $2; my $args = $3; -- cgit v1.2.3