[PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[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 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(-)

-- 
2.9.3

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

[Paolo Bonzini]

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 <pbonzini@redhat.com>
---
 scripts/kernel-doc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 030fc633acd4..c1ea91c2e497 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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;
 }
 
-- 
2.9.3

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

[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 <pbonzini@redhat.com>
---
 scripts/kernel-doc | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index c1ea91c2e497..265ea16cbe22 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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)
-- 
2.9.3

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

[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 <pbonzini@redhat.com>
---
 scripts/kernel-doc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 265ea16cbe22..e5b5daa147ea 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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";
-- 
2.9.3

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

[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 <pbonzini@redhat.com>
---
 scripts/kernel-doc | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e5b5daa147ea..88c3290b6056 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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 = "";
 
-- 
2.9.3

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

[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 <pbonzini@redhat.com>
---
 scripts/kernel-doc | 68 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 50 insertions(+), 18 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 88c3290b6056..daf5e36055b7 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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 = "";
 
-- 
2.9.3

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[Jani Nikula]

On Mon, 02 Jan 2017, Paolo Bonzini <pbonzini@redhat.com> wrote:
> 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 <jani.nikula@intel.com>

> 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.


>
> 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(-)

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[Paolo Bonzini]

On 03/01/2017 10:57, Jani Nikula wrote:
> On Mon, 02 Jan 2017, Paolo Bonzini <pbonzini@redhat.com> wrote:
>> 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 <jani.nikula@intel.com>

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

>> 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

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[Jani Nikula]

On Wed, 04 Jan 2017, Paolo Bonzini <pbonzini@redhat.com> wrote:
> On 03/01/2017 10:57, Jani Nikula wrote:
>> On Mon, 02 Jan 2017, Paolo Bonzini <pbonzini@redhat.com> wrote:
>>> 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 <jani.nikula@intel.com>
>
> Thanks---Perl's not that bad, come on! :)

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

>>> 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

> 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.


>
> Paolo

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[Jonathan Corbet]

On Mon,  2 Jan 2017 16:22:22 +0100
Paolo Bonzini <pbonzini@redhat.com> 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

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[Markus Heiser]

Am 04.01.2017 um 23:06 schrieb Jonathan Corbet <corbet@lwn.net>:

> On Mon,  2 Jan 2017 16:22:22 +0100
> Paolo Bonzini <pbonzini@redhat.com> 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.

Hi Paolo !

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

  https://www.mail-archive.com/linux-doc@vger.kernel.org/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 --

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[Paolo Bonzini]

On 23/01/2017 14:42, Markus Heiser wrote:
> 
> Am 04.01.2017 um 23:06 schrieb Jonathan Corbet <corbet@lwn.net>:
> 
>> On Mon,  2 Jan 2017 16:22:22 +0100
>> Paolo Bonzini <pbonzini@redhat.com> 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.
> 
> Hi Paolo !
> 
> Sorry for my late reply, I'am testing patch 2:
> 
>   https://www.mail-archive.com/linux-doc@vger.kernel.org/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

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

[Markus Heiser]

Am 23.01.2017 um 14:58 schrieb Paolo Bonzini <pbonzini@redhat.com>:
>> 
>> Hi Paolo !
>> 
>> Sorry for my late reply, I'am testing patch 2:
>> 
>>  https://www.mail-archive.com/linux-doc@vger.kernel.org/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 --