Merge tag 'docs-4.9' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "This is the documentation update pull for the 4.9 merge window.

  The Sphinx transition is still creating a fair amount of work. Here we
  have a number of fixes and, importantly, a proper PDF output solution,
  thanks to Jani Nikula, Mauro Carvalho Chehab and Markus Heiser.

  I've started a couple of new books: a driver API book (based on the
  old device-drivers.tmpl) and a development tools book. Both are meant
  to show how we can integrate together our existing documentation into
  a more coherent and accessible whole. It involves moving some stuff
  around and formatting changes, but, I think, the results are worth it.
  The good news is that most of our existing Documentation/*.txt files
  are *almost* in RST format already; the amount of messing around
  required is minimal.

  And, of course, there's the usual set of updates, typo fixes, and
  more"

* tag 'docs-4.9' of git://git.lwn.net/linux: (120 commits)
  URL changed for Linux Foundation TAB
  dax : Fix documentation with respect to struct pages
  iio: Documentation: Correct the path used to create triggers.
  docs: Remove space-before-label guidance from CodingStyle
  docs-rst: add inter-document cross references
  Documentation/email-clients.txt: convert it to ReST markup
  Documentation/kernel-docs.txt: reorder based on timestamp
  Documentation/kernel-docs.txt: Add dates for online docs
  Documentation/kernel-docs.txt: get rid of broken docs
  Documentation/kernel-docs.txt: move in-kernel docs
  Documentation/kernel-docs.txt: remove more legacy references
  Documentation/kernel-docs.txt: add two published books
  Documentation/kernel-docs.txt: sort books per publication date
  Documentation/kernel-docs.txt: adjust LDD references
  Documentation/kernel-docs.txt: some improvements on the ReST output
  Documentation/kernel-docs.txt: Consistent indenting: 4 spaces
  Documentation/kernel-docs.txt: Add 4 paper/book references
  Documentation/kernel-docs.txt: Improve layouting of book list
  Documentation/kernel-docs.txt: Remove offline or outdated entries
  docs: Clean up bare :: lines
  ...

1 files changed, 32 insertions, 16 deletions

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 4f2e9049e8fa..93721f3c91bf 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -212,6 +212,7 @@ my $anon_struct_union = 0;
 my $type_constant = '\%([-_\w]+)';
 my $type_func = '(\w+)\(\)';
 my $type_param = '\@(\w+)';
+my $type_fp_param = '\@(\w+)\(\)';  # Special RST handling for func ptr params
 my $type_struct = '\&((struct\s*)*[_\w]+)';
 my $type_struct_xml = '\\&((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
@@ -292,6 +293,7 @@ my @highlights_rst = (
                        # Note: need to escape () to avoid func matching later
                        [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"],
                        [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"],
+		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
                        [$type_func, "\\:c\\:func\\:`\$1()`"],
                        [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
                        [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
@@ -412,7 +414,7 @@ my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
 my $doc_sect = $doc_com . 
-    '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)';
+    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -1831,13 +1833,22 @@ sub output_function_rst(%) {
     my %args = %{$_[0]};
     my ($parameter, $section);
     my $oldprefix = $lineprefix;
-    my $start;
-
-    print ".. c:function:: ";
+    my $start = "";
+
+    if ($args{'typedef'}) {
+	print ".. c:type:: ". $args{'function'} . "\n\n";
+	print_lineno($declaration_start_line);
+	print "   **Typedef**: ";
+	$lineprefix = "";
+	output_highlight_rst($args{'purpose'});
+	$start = "\n\n**Syntax**\n\n  ``";
+    } else {
+	print ".. c:function:: ";
+    }
     if ($args{'functiontype'} ne "") {
-	$start = $args{'functiontype'} . " " . $args{'function'} . " (";
+	$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
     } else {
-	$start = $args{'function'} . " (";
+	$start .= $args{'function'} . " (";
     }
     print $start;
 
@@ -1849,9 +1860,6 @@ sub output_function_rst(%) {
 	$count++;
 	$type = $args{'parametertypes'}{$parameter};
 
-	# RST doesn't like address_space tags at function prototypes
-	$type =~ s/__(user|kernel|iomem|percpu|pmem|rcu)\s*//;
-
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
 	    # pointer-to-function
 	    print $1 . $parameter . ") (" . $2;
@@ -1859,11 +1867,15 @@ sub output_function_rst(%) {
 	    print $type . " " . $parameter;
 	}
     }
-    print ")\n\n";
-    print_lineno($declaration_start_line);
-    $lineprefix = "   ";
-    output_highlight_rst($args{'purpose'});
-    print "\n";
+    if ($args{'typedef'}) {
+	print ");``\n\n";
+    } else {
+	print ")\n\n";
+	print_lineno($declaration_start_line);
+	$lineprefix = "   ";
+	output_highlight_rst($args{'purpose'});
+	print "\n";
+    }
 
     print "**Parameters**\n\n";
     $lineprefix = "  ";
@@ -2003,7 +2015,7 @@ sub output_struct_rst(%) {
 	($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
         print_lineno($parameterdesc_start_lines{$parameter_name});
-	print "``$type $parameter``\n";
+	print "``" . $parameter . "``\n";
 	output_highlight_rst($args{'parameterdescs'}{$parameter_name});
 	print "\n";
     }
@@ -2193,7 +2205,9 @@ sub dump_typedef($$) {
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
 
     # Parse function prototypes
-    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/) {
+    if ($x =~ /typedef\s+(\w+)\s*\(\*\s*(\w\S+)\s*\)\s*\((.*)\);/ ||
+	$x =~ /typedef\s+(\w+)\s*(\w\S+)\s*\s*\((.*)\);/) {
+
 	# Function typedefs
 	$return_type = $1;
 	$declaration_name = $2;
@@ -2204,6 +2218,7 @@ sub dump_typedef($$) {
 	output_declaration($declaration_name,
 			   'function',
 			   {'function' => $declaration_name,
+			    'typedef' => 1,
 			    'module' => $modulename,
 			    'functiontype' => $return_type,
 			    'parameterlist' => \@parameterlist,
@@ -2338,6 +2353,7 @@ sub push_parameter($$$) {
 
 	if ($type eq "" && $param =~ /\.\.\.$/)
 	{
+	    $param = "...";
 	    if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") {
 		$parameterdescs{$param} = "variable arguments";
 	    }