Skip to contentSkip to conversation

kernel-doc tweaks and cleanup of rST vs. non-rST backends

PATCH In review Paolo Bonzini 4 participants 13 messages Jan 2, 2017 – Jan 23, 2017

lore
Share & tools
lore

Paolo Bonzini

author
#0 lore raw

cover kernel-doc tweaks and cleanup of rST vs. non-rST backends

Hi,

these patches are the result of my experiments with using kernel-doc for QEMU's documentation. Patches 1 and 2 should be relatively straightforward, as they are simple bugfixes. Patches 3 to 5, instead, are making the docbook backend (and the others too) more consistent with the input and output of the rST backend.

I am not sure what is the state of the kernel-doc non-rST backends; but there are still several books using the docbook workflow, so I'm trying my luck and sending the patches anyway. :)

Paolo

Paolo Bonzini (5):
kernel-doc: cleanup parameter type in function-typed arguments
kernel-doc: strip attributes even if they have an argument
kernel-doc: include parameter type in docbook output
kernel-doc: make member highlighting available in all backends
kernel-doc: make highlights more homogenous for the various backends

 scripts/kernel-doc | 99 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 74 insertions(+), 25 deletions(-)
Signature · 1 line
2.9.3
author
#1 lore raw

PATCH 1/5 kernel-doc: cleanup parameter type in function-typed arguments

A prototype like

/**
* foo - sample definition
* @bar: a parameter
*/
int foo(int (*bar)(int x,
int y));

is currently producing

.. c:function:: int foo (int (*bar) (int x, int y)

sample definition

**Parameters**

``int (*)(int x, int y) bar``
a parameter

Collapse the spaces so that the output is nicer.

Signed-off-by Paolo Bonzini <[email protected]>
---
 scripts/kernel-doc | 1 +
 1 file changed, 1 insertion(+)
scripts/kernel-doc +1 -0
index 030fc633acd4..c1ea91c2e497 100755
@@ -2409,6 +2409,7 @@ sub push_parameter($$$) {
 	# "[blah" in a parameter string;
 	###$param =~ s/\s*//g;
 	push @parameterlist, $param;
+	$type =~ s/\s\s+/ /g;
 	$parametertypes{$param} = $type;
 }
Signature · 1 line
2.9.3
author
#2 lore raw

PATCH 2/5 kernel-doc: strip attributes even if they have an argument

In reply to Paolo Bonzini

An inline function can have an attribute, as in include/linux/log2.h, and kernel-doc handles this already for simple cases. However, some attributes have arguments (e.g. the "target" attribute). Handle those too.

Furthermore, attributes could be at the beginning of a function declaration, before the return type. To correctly handle this case, you need to strip spaces after the attributes; otherwise, dump_function is left confused.

Signed-off-by Paolo Bonzini <[email protected]>
---
 scripts/kernel-doc | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)
scripts/kernel-doc +7 -1
index c1ea91c2e497..265ea16cbe22 100755
@@ -2506,7 +2506,13 @@ sub dump_function($$) {
     $prototype =~ s/__must_check +//;
     $prototype =~ s/__weak +//;
     my $define = $prototype =~ s/^#\s*define\s+//; #ak added
-    $prototype =~ s/__attribute__\s*\(\([a-z,]*\)\)//;
+    $prototype =~ s/__attribute__\s*\(\(
+            (?:
+                 [\w\s]++          # attribute name
+                 (?:\([^)]*+\))?   # attribute arguments
+                 \s*+,?            # optional comma at the end
+            )+
+          \)\)\s+//x;
 
     # Yes, this truly is vile.  We are looking for:
     # 1. Return type (may be nothing if we're looking at a macro)
Signature · 1 line
2.9.3
author
#3 lore raw

PATCH 3/5 kernel-doc: include parameter type in docbook output

In reply to Paolo Bonzini

The restructuredText output includes both the parameter type and the name for functions and function-typed members. Do the same for docbook.

Signed-off-by Paolo Bonzini <[email protected]>
---
 scripts/kernel-doc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
scripts/kernel-doc +4 -2
index 265ea16cbe22..e5b5daa147ea 100755
@@ -1131,8 +1131,9 @@ sub output_function_xml(%) {
 	foreach $parameter (@{$args{'parameterlist'}}) {
 	    my $parameter_name = $parameter;
 	    $parameter_name =~ s/\[.*//;
+	    $type = $args{'parametertypes'}{$parameter};
 
-	    print "  <varlistentry>\n   <term><parameter>$parameter</parameter></term>\n";
+	    print "  <varlistentry>\n   <term><parameter>$type $parameter</parameter></term>\n";
 	    print "   <listitem>\n    <para>\n";
 	    $lineprefix="     ";
 	    output_highlight($args{'parameterdescs'}{$parameter_name});

@@ -1223,8 +1224,9 @@ sub output_struct_xml(%) {
 
       defined($args{'parameterdescs'}{$parameter_name}) || next;
       ($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
+      $type = $args{'parametertypes'}{$parameter};
       print "    <varlistentry>";
-      print "      <term>$parameter</term>\n";
+      print "      <term><literal>$type $parameter</literal></term>\n";
       print "      <listitem><para>\n";
       output_highlight($args{'parameterdescs'}{$parameter_name});
       print "      </para></listitem>\n";
Signature · 1 line
2.9.3
author
#4 lore raw

PATCH 4/5 kernel-doc: make member highlighting available in all backends

In reply to Paolo Bonzini

Note that, in order to produce the correct Docbook markup, the "." or "->" must be separated from the member name in the regex's captured fields. For consistency, this change is applied to $type_member and $type_member_func too, not just to $type_member_xml.

List mode only prints the struct name, to avoid any undesired change in the operation of docproc.

Signed-off-by Paolo Bonzini <[email protected]>
---
 scripts/kernel-doc | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)
scripts/kernel-doc +19 -11
index e5b5daa147ea..88c3290b6056 100755
@@ -199,12 +199,12 @@ EOF
 # 'funcname()' - function
 # '$ENVVAR' - environmental variable
 # '&struct_name' - name of a structure (up to two words including 'struct')
+# '&struct_name.member' - name of a structure member
 # '@parameter' - name of a parameter
 # '%CONST' - name of a constant.
 
 ## init lots of data
 
-
 my $errors = 0;
 my $warnings = 0;
 my $anon_struct_union = 0;

@@ -221,7 +221,8 @@ my $type_enum_full = '\&(enum)\s*([_\w]+)';
 my $type_struct_full = '\&(struct)\s*([_\w]+)';
 my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
 my $type_union_full = '\&(union)\s*([_\w]+)';
-my $type_member = '\&([_\w]+)((\.|->)[_\w]+)';
+my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
+my $type_member_xml = '\&amp;([_\w]+)(\.|-\&gt;)([_\w]+)';
 my $type_member_func = $type_member . '\(\)';
 
 # Output conversion substitutions.

@@ -233,7 +234,8 @@ my @highlights_html = (
                        [$type_func, "<b>\$1</b>"],
                        [$type_struct_xml, "<i>\$1</i>"],
                        [$type_env, "<b><i>\$1</i></b>"],
-                       [$type_param, "<tt><b>\$1</b></tt>"]
+                       [$type_param, "<tt><b>\$1</b></tt>"],
+                       [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"]
                       );
 my $local_lt = "\\\\\\\\lt:";
 my $local_gt = "\\\\\\\\gt:";

@@ -245,7 +247,8 @@ my @highlights_html5 = (
                         [$type_func, "<span class=\"func\">\$1</span>"],
                         [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
                         [$type_env, "<span class=\"env\">\$1</span>"],
-                        [$type_param, "<span class=\"param\">\$1</span>]"]
+                        [$type_param, "<span class=\"param\">\$1</span>]"],
+                        [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"]
 		       );
 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 

@@ -256,7 +259,8 @@ my @highlights_xml = (
                       [$type_struct_xml, "<structname>\$1</structname>"],
                       [$type_param, "<parameter>\$1</parameter>"],
                       [$type_func, "<function>\$1</function>"],
-                      [$type_env, "<envar>\$1</envar>"]
+                      [$type_env, "<envar>\$1</envar>"],
+                      [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"]
 		     );
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
 

@@ -266,7 +270,8 @@ my @highlights_gnome = (
                         [$type_func, "<function>\$1</function>"],
                         [$type_struct, "<structname>\$1</structname>"],
                         [$type_env, "<envar>\$1</envar>"],
-                        [$type_param, "<parameter>\$1</parameter>" ]
+                        [$type_param, "<parameter>\$1</parameter>" ],
+                        [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"]
 		       );
 my $blankline_gnome = "</para><para>\n";
 

@@ -275,7 +280,8 @@ my @highlights_man = (
                       [$type_constant, "\$1"],
                       [$type_func, "\\\\fB\$1\\\\fP"],
                       [$type_struct, "\\\\fI\$1\\\\fP"],
-                      [$type_param, "\\\\fI\$1\\\\fP"]
+                      [$type_param, "\\\\fI\$1\\\\fP"],
+                      [$type_member, "\\\\fI\$1\$2\$3\\\\fP"]
 		     );
 my $blankline_man = "";
 

@@ -284,7 +290,8 @@ my @highlights_text = (
                        [$type_constant, "\$1"],
                        [$type_func, "\$1"],
                        [$type_struct, "\$1"],
-                       [$type_param, "\$1"]
+                       [$type_param, "\$1"],
+                       [$type_member, "\$1\$2\$3"]
 		      );
 my $blankline_text = "";
 

@@ -292,8 +299,8 @@ my $blankline_text = "";
 my @highlights_rst = (
                        [$type_constant, "``\$1``"],
                        # 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_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\\(\\\\) <\$1>`"],
+                       [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],
 		       [$type_fp_param, "**\$1\\\\(\\\\)**"],
                        [$type_func, "\\:c\\:func\\:`\$1()`"],
                        [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],

@@ -311,7 +318,8 @@ my @highlights_list = (
                        [$type_constant, "\$1"],
                        [$type_func, "\$1"],
                        [$type_struct, "\$1"],
-                       [$type_param, "\$1"]
+                       [$type_param, "\$1"],
+                       [$type_member, "\$1"]
 		      );
 my $blankline_list = "";
Signature · 1 line
2.9.3
author
#5 lore raw

PATCH 5/5 kernel-doc: make highlights more homogenous for the various backends

In reply to Paolo Bonzini

$type_struct_full and friends are only used by the restructuredText backend, because it needs to separate enum/struct/typedef/union from the name of the type. However, $type_struct is *also* used by the rST backend. This is confusing.

This patch replaces $type_struct's use in the rST backend with a new $type_fallback; it modifies $type_struct so that it can be used in the rST backend; and creates regular expressions like $type_struct for enum/typedef/union, for use in all backends.

Note that, compared to $type_*_full, in the new regexes $1 includes both the "kind" and the name (before, $1 was pretty much a constant).

Signed-off-by Paolo Bonzini <[email protected]>
---
 scripts/kernel-doc | 68 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 50 insertions(+), 18 deletions(-)
scripts/kernel-doc +50 -18
index 88c3290b6056..daf5e36055b7 100755
@@ -214,15 +214,19 @@ 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 = '\\&amp;((struct\s*)*[_\w]+)';
 my $type_env = '(\$\w+)';
-my $type_enum_full = '\&(enum)\s*([_\w]+)';
-my $type_struct_full = '\&(struct)\s*([_\w]+)';
-my $type_typedef_full = '\&(typedef)\s*([_\w]+)';
-my $type_union_full = '\&(union)\s*([_\w]+)';
+my $type_enum = '\&(enum\s*([_\w]+))';
+my $type_struct = '\&(struct\s*([_\w]+))';
+my $type_typedef = '\&(typedef\s*([_\w]+))';
+my $type_union = '\&(union\s*([_\w]+))';
 my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';
+my $type_fallback = '\&([_\w]+)';
+my $type_enum_xml = '\&amp;(enum\s*([_\w]+))';
+my $type_struct_xml = '\&amp;(struct\s*([_\w]+))';
+my $type_typedef_xml = '\&amp;(typedef\s*([_\w]+))';
+my $type_union_xml = '\&amp;(union\s*([_\w]+))';
 my $type_member_xml = '\&amp;([_\w]+)(\.|-\&gt;)([_\w]+)';
+my $type_fallback_xml = '\&amp([_\w]+)';
 my $type_member_func = $type_member . '\(\)';
 
 # Output conversion substitutions.

@@ -232,10 +236,14 @@ my $type_member_func = $type_member . '\(\)';
 my @highlights_html = (
                        [$type_constant, "<i>\$1</i>"],
                        [$type_func, "<b>\$1</b>"],
+                       [$type_enum_xml, "<i>\$1</i>"],
                        [$type_struct_xml, "<i>\$1</i>"],
+                       [$type_typedef_xml, "<i>\$1</i>"],
+                       [$type_union_xml, "<i>\$1</i>"],
                        [$type_env, "<b><i>\$1</i></b>"],
                        [$type_param, "<tt><b>\$1</b></tt>"],
-                       [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"]
+                       [$type_member_xml, "<tt><i>\$1</i>\$2\$3</tt>"],
+                       [$type_fallback_xml, "<i>\$1</i>"]
                       );
 my $local_lt = "\\\\\\\\lt:";
 my $local_gt = "\\\\\\\\gt:";

@@ -245,10 +253,14 @@ my $blankline_html = $local_lt . "p" . $local_gt;	# was "<p>"
 my @highlights_html5 = (
                         [$type_constant, "<span class=\"const\">\$1</span>"],
                         [$type_func, "<span class=\"func\">\$1</span>"],
+                        [$type_enum_xml, "<span class=\"enum\">\$1</span>"],
                         [$type_struct_xml, "<span class=\"struct\">\$1</span>"],
+                        [$type_typedef_xml, "<span class=\"typedef\">\$1</span>"],
+                        [$type_union_xml, "<span class=\"union\">\$1</span>"],
                         [$type_env, "<span class=\"env\">\$1</span>"],
                         [$type_param, "<span class=\"param\">\$1</span>]"],
-                        [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"]
+                        [$type_member_xml, "<span class=\"literal\"><span class=\"struct\">\$1</span>\$2<span class=\"member\">\$3</span></span>"],
+                        [$type_fallback_xml, "<span class=\"struct\">\$1</span>"]
 		       );
 my $blankline_html5 = $local_lt . "br /" . $local_gt;
 

@@ -256,11 +268,15 @@ my $blankline_html5 = $local_lt . "br /" . $local_gt;
 my @highlights_xml = (
                       ["([^=])\\\"([^\\\"<]+)\\\"", "\$1<quote>\$2</quote>"],
                       [$type_constant, "<constant>\$1</constant>"],
+                      [$type_enum_xml, "<type>\$1</type>"],
                       [$type_struct_xml, "<structname>\$1</structname>"],
+                      [$type_typedef_xml, "<type>\$1</type>"],
+                      [$type_union_xml, "<structname>\$1</structname>"],
                       [$type_param, "<parameter>\$1</parameter>"],
                       [$type_func, "<function>\$1</function>"],
                       [$type_env, "<envar>\$1</envar>"],
-                      [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"]
+                      [$type_member_xml, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
+                      [$type_fallback_xml, "<structname>\$1</structname>"]
 		     );
 my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $local_gt . "\n";
 

@@ -268,10 +284,14 @@ my $blankline_xml = $local_lt . "/para" . $local_gt . $local_lt . "para" . $loca
 my @highlights_gnome = (
                         [$type_constant, "<replaceable class=\"option\">\$1</replaceable>"],
                         [$type_func, "<function>\$1</function>"],
+                        [$type_enum, "<type>\$1</type>"],
                         [$type_struct, "<structname>\$1</structname>"],
+                        [$type_typedef, "<type>\$1</type>"],
+                        [$type_union, "<structname>\$1</structname>"],
                         [$type_env, "<envar>\$1</envar>"],
                         [$type_param, "<parameter>\$1</parameter>" ],
-                        [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"]
+                        [$type_member, "<literal><structname>\$1</structname>\$2<structfield>\$3</structfield></literal>"],
+                        [$type_fallback, "<structname>\$1</structname>"]
 		       );
 my $blankline_gnome = "</para><para>\n";
 

@@ -279,9 +299,13 @@ my $blankline_gnome = "</para><para>\n";
 my @highlights_man = (
                       [$type_constant, "\$1"],
                       [$type_func, "\\\\fB\$1\\\\fP"],
+                      [$type_enum, "\\\\fI\$1\\\\fP"],
                       [$type_struct, "\\\\fI\$1\\\\fP"],
+                      [$type_typedef, "\\\\fI\$1\\\\fP"],
+                      [$type_union, "\\\\fI\$1\\\\fP"],
                       [$type_param, "\\\\fI\$1\\\\fP"],
-                      [$type_member, "\\\\fI\$1\$2\$3\\\\fP"]
+                      [$type_member, "\\\\fI\$1\$2\$3\\\\fP"],
+                      [$type_fallback, "\\\\fI\$1\\\\fP"]
 		     );
 my $blankline_man = "";
 

@@ -289,9 +313,13 @@ my $blankline_man = "";
 my @highlights_text = (
                        [$type_constant, "\$1"],
                        [$type_func, "\$1"],
+                       [$type_enum, "\$1"],
                        [$type_struct, "\$1"],
+                       [$type_typedef, "\$1"],
+                       [$type_union, "\$1"],
                        [$type_param, "\$1"],
-                       [$type_member, "\$1\$2\$3"]
+                       [$type_member, "\$1\$2\$3"],
+                       [$type_fallback, "\$1"]
 		      );
 my $blankline_text = "";
 

@@ -303,12 +331,12 @@ my @highlights_rst = (
                        [$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$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>`"],
-                       [$type_typedef_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
-                       [$type_union_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],
+                       [$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],
+                       [$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],
+                       [$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],
+                       [$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],
                        # in rst this can refer to any type
-                       [$type_struct, "\\:c\\:type\\:`\$1`"],
+                       [$type_fallback, "\\:c\\:type\\:`\$1`"],
                        [$type_param, "**\$1**"]
 		      );
 my $blankline_rst = "\n";

@@ -317,9 +345,13 @@ my $blankline_rst = "\n";
 my @highlights_list = (
                        [$type_constant, "\$1"],
                        [$type_func, "\$1"],
+                       [$type_enum, "\$1"],
                        [$type_struct, "\$1"],
+                       [$type_typedef, "\$1"],
+                       [$type_union, "\$1"],
                        [$type_param, "\$1"],
-                       [$type_member, "\$1"]
+                       [$type_member, "\$1"],
+                       [$type_fallback, "\$1"]
 		      );
 my $blankline_list = "";
Signature · 1 line
2.9.3
Acked-by on the v1 series
#6 lore raw
In reply to Paolo Bonzini
Quoted 7 lines · Paolo Bonzini

Hi,

these patches are the result of my experiments with using kernel-doc for QEMU's documentation. Patches 1 and 2 should be relatively straightforward, as they are simple bugfixes. Patches 3 to 5, instead, are making the docbook backend (and the others too) more consistent with the input and output of the rST backend.

I did not test the patches, and for sure I will not attempt reviewing perl, but at a high level the changes seem sensible.

Acked-by Jani Nikula <[email protected]>
Quoted 3 lines

I am not sure what is the state of the kernel-doc non-rST backends; but there are still several books using the docbook workflow, so I'm trying my luck and sending the patches anyway. :)

Obviously reStructuredText is the main output now and has to work, and DocBook is still used as you say, but hopefully you sneaked in regressions for the other formats so we can gauge if anyone cares! ;)

BR,
Jani.

Quoted 12 lines

Paolo

Paolo Bonzini (5):
kernel-doc: cleanup parameter type in function-typed arguments
kernel-doc: strip attributes even if they have an argument
kernel-doc: include parameter type in docbook output
kernel-doc: make member highlighting available in all backends
kernel-doc: make highlights more homogenous for the various backends

 scripts/kernel-doc | 99 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 74 insertions(+), 25 deletions(-)
Signature · 1 line
Jani Nikula, Intel Open Source Technology Center
author
#7 lore raw
Quoted 9 lines · Jani Nikula
Quoted 7 lines · Paolo Bonzini

Hi,

these patches are the result of my experiments with using kernel-doc for QEMU's documentation. Patches 1 and 2 should be relatively straightforward, as they are simple bugfixes. Patches 3 to 5, instead, are making the docbook backend (and the others too) more consistent with the input and output of the rST backend.

Quoted 4 lines

I did not test the patches, and for sure I will not attempt reviewing perl, but at a high level the changes seem sensible.

Acked-by Jani Nikula <[email protected]>

Thanks---Perl's not that bad, come on! :)

Quoted 7 lines
Quoted 3 lines

I am not sure what is the state of the kernel-doc non-rST backends; but there are still several books using the docbook workflow, so I'm trying my luck and sending the patches anyway. :)

Obviously reStructuredText is the main output now and has to work, and DocBook is still used as you say, but hopefully you sneaked in regressions for the other formats so we can gauge if anyone cares! ;)

Couldn't expect any other deprecation plan from a graphics guy!

FWIW I tested building the Sphinx and DocBook books and eyeballed the output for both of them. I also tested manually the list backend on toy testcases, and of course it is used by docproc when building DocBook manuals. I didn't test the other backends.

Paolo

#8 lore raw
Quoted 10 lines · Paolo Bonzini
Quoted 9 lines · Jani Nikula
Quoted 7 lines · Paolo Bonzini

Hi,

these patches are the result of my experiments with using kernel-doc for QEMU's documentation. Patches 1 and 2 should be relatively straightforward, as they are simple bugfixes. Patches 3 to 5, instead, are making the docbook backend (and the others too) more consistent with the input and output of the rST backend.

Quoted 6 lines
Quoted 4 lines

I did not test the patches, and for sure I will not attempt reviewing perl, but at a high level the changes seem sensible.

Acked-by Jani Nikula <[email protected]>

Thanks---Perl's not that bad, come on! :)

FWIW 99% of all the Perl I've ever written or read is in kernel-doc...!

Quoted 9 lines
Quoted 7 lines
Quoted 3 lines

I am not sure what is the state of the kernel-doc non-rST backends; but there are still several books using the docbook workflow, so I'm trying my luck and sending the patches anyway. :)

Obviously reStructuredText is the main output now and has to work, and DocBook is still used as you say, but hopefully you sneaked in regressions for the other formats so we can gauge if anyone cares! ;)

Couldn't expect any other deprecation plan from a graphics guy!

Auch, don't hit me below the belt! :p

Quoted 4 lines

FWIW I tested building the Sphinx and DocBook books and eyeballed the output for both of them. I also tested manually the list backend on toy testcases, and of course it is used by docproc when building DocBook manuals. I didn't test the other backends.

BTW one thing I did a lot while making supposedly benign changes to kernel-doc was:

$ make cleandocs
$ make htmldocs
$ mv Documentation/output Documentation/output.before
$ # apply the change
$ make htmldocs
$ diff -r Documentation/output.before Documentation/output

There's some noise from .doctrees that you can safely ignore, but otherwise it was a life saver.

BR,
Jani.

Quoted 2 lines

Paolo

Signature · 1 line
Jani Nikula, Intel Open Source Technology Center
#9 lore raw
In reply to Paolo Bonzini
Quoted 9 lines · On Mon, 2 Jan 2017 16:22:22 +0100 Paolo Bonzini <[email protected]> wrote:

these patches are the result of my experiments with using kernel-doc for QEMU's documentation. Patches 1 and 2 should be relatively straightforward, as they are simple bugfixes. Patches 3 to 5, instead, are making the docbook backend (and the others too) more consistent with the input and output of the rST backend.

I am not sure what is the state of the kernel-doc non-rST backends; but there are still several books using the docbook workflow, so I'm trying my luck and sending the patches anyway. :)

I've played with them a bit, and they don't seem to break things, so I'll go ahead and apply them.

Thanks,

jon

#10 lore raw

Am 04.01.2017 um 23:06 schrieb Jonathan Corbet <[email protected]>:

Quoted 9 lines
Quoted 6 lines · On Mon, 2 Jan 2017 16:22:22 +0100 Paolo Bonzini <[email protected]> wrote:

these patches are the result of my experiments with using kernel-doc for QEMU's documentation. Patches 1 and 2 should be relatively straightforward, as they are simple bugfixes. Patches 3 to 5, instead, are making the docbook backend (and the others too) more consistent with the input and output of the rST backend.

Quoted 6 lines
Quoted 3 lines

I am not sure what is the state of the kernel-doc non-rST backends; but there are still several books using the docbook workflow, so I'm trying my luck and sending the patches anyway. :)

I've played with them a bit, and they don't seem to break things, so I'll go ahead and apply them.

Hi Paolo !

Sorry for my late reply, I'am testing patch 2:

https://www.mail-archive.com/[email protected]/msg08503.html

but I can't find any changes in the reST output (even not in include/linux/log2.h you mentioned). May I'm a bit blind today, so can you give me an example where the patch takes effect?

Thanks,

-- Markus --

author
#11 lore raw
Quoted 21 lines · Markus Heiser

Am 04.01.2017 um 23:06 schrieb Jonathan Corbet <[email protected]>:

Quoted 9 lines
Quoted 6 lines · On Mon, 2 Jan 2017 16:22:22 +0100 Paolo Bonzini <[email protected]> wrote:

these patches are the result of my experiments with using kernel-doc for QEMU's documentation. Patches 1 and 2 should be relatively straightforward, as they are simple bugfixes. Patches 3 to 5, instead, are making the docbook backend (and the others too) more consistent with the input and output of the rST backend.

Quoted 6 lines
Quoted 3 lines

I am not sure what is the state of the kernel-doc non-rST backends; but there are still several books using the docbook workflow, so I'm trying my luck and sending the patches anyway. :)

I've played with them a bit, and they don't seem to break things, so I'll go ahead and apply them.

Hi Paolo !

Quoted 7 lines

Sorry for my late reply, I'am testing patch 2:

https://www.mail-archive.com/[email protected]/msg08503.html

but I can't find any changes in the reST output (even not in include/linux/log2.h you mentioned). May I'm a bit blind today, so can you give me an example where the patch takes effect?

I found this with QEMU. You need to test with an inline function which has attributes with arguments.

Paolo

#12 lore raw

Am 23.01.2017 um 14:58 schrieb Paolo Bonzini <[email protected]>:

Quoted 5 lines
Quoted 5 lines

Hi Paolo !

Sorry for my late reply, I'am testing patch 2:

Quoted 8 lines
Quoted 5 lines

https://www.mail-archive.com/[email protected]/msg08503.html

but I can't find any changes in the reST output (even not in include/linux/log2.h you mentioned). May I'm a bit blind today, so can you give me an example where the patch takes effect?

I found this with QEMU. You need to test with an inline function which has attributes with arguments.

Ah, mostly about QEMU .. OK now I see also a small effect on kernel's source:

https://github.com/return42/sphkerneldoc/commit/cecfe275

Sorry for the noise.

-- Markus --