* [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends @ 2017-01-02 15:22 Paolo Bonzini 2017-01-02 15:22 ` [PATCH 1/5] kernel-doc: cleanup parameter type in function-typed arguments Paolo Bonzini ` (6 more replies) 0 siblings, 7 replies; 13+ messages in thread From: Paolo Bonzini @ 2017-01-02 15:22 UTC (permalink / raw) To: linux-kernel, linux-doc; +Cc: corbet 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* [PATCH 1/5] kernel-doc: cleanup parameter type in function-typed arguments 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini @ 2017-01-02 15:22 ` Paolo Bonzini 2017-01-02 15:22 ` [PATCH 2/5] kernel-doc: strip attributes even if they have an argument Paolo Bonzini ` (5 subsequent siblings) 6 siblings, 0 replies; 13+ messages in thread From: Paolo Bonzini @ 2017-01-02 15:22 UTC (permalink / raw) To: linux-kernel, linux-doc; +Cc: corbet 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 ^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 2/5] kernel-doc: strip attributes even if they have an argument 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini 2017-01-02 15:22 ` [PATCH 1/5] kernel-doc: cleanup parameter type in function-typed arguments Paolo Bonzini @ 2017-01-02 15:22 ` Paolo Bonzini 2017-01-02 15:22 ` [PATCH 3/5] kernel-doc: include parameter type in docbook output Paolo Bonzini ` (4 subsequent siblings) 6 siblings, 0 replies; 13+ messages in thread From: Paolo Bonzini @ 2017-01-02 15:22 UTC (permalink / raw) To: linux-kernel, linux-doc; +Cc: corbet 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 ^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 3/5] kernel-doc: include parameter type in docbook output 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini 2017-01-02 15:22 ` [PATCH 1/5] kernel-doc: cleanup parameter type in function-typed arguments Paolo Bonzini 2017-01-02 15:22 ` [PATCH 2/5] kernel-doc: strip attributes even if they have an argument Paolo Bonzini @ 2017-01-02 15:22 ` Paolo Bonzini 2017-01-02 15:22 ` [PATCH 4/5] kernel-doc: make member highlighting available in all backends Paolo Bonzini ` (3 subsequent siblings) 6 siblings, 0 replies; 13+ messages in thread From: Paolo Bonzini @ 2017-01-02 15:22 UTC (permalink / raw) To: linux-kernel, linux-doc; +Cc: corbet 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 ^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 4/5] kernel-doc: make member highlighting available in all backends 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini ` (2 preceding siblings ...) 2017-01-02 15:22 ` [PATCH 3/5] kernel-doc: include parameter type in docbook output Paolo Bonzini @ 2017-01-02 15:22 ` Paolo Bonzini 2017-01-02 15:22 ` [PATCH 5/5] kernel-doc: make highlights more homogenous for the various backends Paolo Bonzini ` (2 subsequent siblings) 6 siblings, 0 replies; 13+ messages in thread From: Paolo Bonzini @ 2017-01-02 15:22 UTC (permalink / raw) To: linux-kernel, linux-doc; +Cc: corbet 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 = '\&([_\w]+)(\.|-\>)([_\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 ^ permalink raw reply related [flat|nested] 13+ messages in thread
* [PATCH 5/5] kernel-doc: make highlights more homogenous for the various backends 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini ` (3 preceding siblings ...) 2017-01-02 15:22 ` [PATCH 4/5] kernel-doc: make member highlighting available in all backends Paolo Bonzini @ 2017-01-02 15:22 ` Paolo Bonzini 2017-01-03 9:57 ` [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Jani Nikula 2017-01-04 22:06 ` Jonathan Corbet 6 siblings, 0 replies; 13+ messages in thread From: Paolo Bonzini @ 2017-01-02 15:22 UTC (permalink / raw) To: linux-kernel, linux-doc; +Cc: corbet $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 = '\\&((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 = '\&(enum\s*([_\w]+))'; +my $type_struct_xml = '\&(struct\s*([_\w]+))'; +my $type_typedef_xml = '\&(typedef\s*([_\w]+))'; +my $type_union_xml = '\&(union\s*([_\w]+))'; my $type_member_xml = '\&([_\w]+)(\.|-\>)([_\w]+)'; +my $type_fallback_xml = '\&([_\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 ^ permalink raw reply related [flat|nested] 13+ messages in thread
* Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini ` (4 preceding siblings ...) 2017-01-02 15:22 ` [PATCH 5/5] kernel-doc: make highlights more homogenous for the various backends Paolo Bonzini @ 2017-01-03 9:57 ` Jani Nikula 2017-01-04 15:13 ` Paolo Bonzini 2017-01-04 22:06 ` Jonathan Corbet 6 siblings, 1 reply; 13+ messages in thread From: Jani Nikula @ 2017-01-03 9:57 UTC (permalink / raw) To: Paolo Bonzini, linux-kernel, linux-doc; +Cc: corbet 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends 2017-01-03 9:57 ` [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Jani Nikula @ 2017-01-04 15:13 ` Paolo Bonzini 2017-01-04 15:40 ` Jani Nikula 0 siblings, 1 reply; 13+ messages in thread From: Paolo Bonzini @ 2017-01-04 15:13 UTC (permalink / raw) To: Jani Nikula, linux-kernel, linux-doc; +Cc: corbet 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends 2017-01-04 15:13 ` Paolo Bonzini @ 2017-01-04 15:40 ` Jani Nikula 0 siblings, 0 replies; 13+ messages in thread From: Jani Nikula @ 2017-01-04 15:40 UTC (permalink / raw) To: Paolo Bonzini, linux-kernel, linux-doc; +Cc: corbet 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini ` (5 preceding siblings ...) 2017-01-03 9:57 ` [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Jani Nikula @ 2017-01-04 22:06 ` Jonathan Corbet 2017-01-23 13:42 ` Markus Heiser 6 siblings, 1 reply; 13+ messages in thread From: Jonathan Corbet @ 2017-01-04 22:06 UTC (permalink / raw) To: Paolo Bonzini; +Cc: linux-kernel, linux-doc 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends 2017-01-04 22:06 ` Jonathan Corbet @ 2017-01-23 13:42 ` Markus Heiser 2017-01-23 13:58 ` Paolo Bonzini 0 siblings, 1 reply; 13+ messages in thread From: Markus Heiser @ 2017-01-23 13:42 UTC (permalink / raw) To: Paolo Bonzini Cc: Jonathan Corbet, linux-kernel@vger.kernel.org List, linux-doc@vger.kernel.org List 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 -- ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends 2017-01-23 13:42 ` Markus Heiser @ 2017-01-23 13:58 ` Paolo Bonzini 2017-01-23 14:38 ` Markus Heiser 0 siblings, 1 reply; 13+ messages in thread From: Paolo Bonzini @ 2017-01-23 13:58 UTC (permalink / raw) To: Markus Heiser Cc: Jonathan Corbet, linux-kernel@vger.kernel.org List, linux-doc@vger.kernel.org List 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 ^ permalink raw reply [flat|nested] 13+ messages in thread
* Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends 2017-01-23 13:58 ` Paolo Bonzini @ 2017-01-23 14:38 ` Markus Heiser 0 siblings, 0 replies; 13+ messages in thread From: Markus Heiser @ 2017-01-23 14:38 UTC (permalink / raw) To: Paolo Bonzini Cc: Jonathan Corbet, linux-kernel@vger.kernel.org List, linux-doc@vger.kernel.org List 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 -- ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2017-01-23 14:39 UTC | newest] Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-01-02 15:22 [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Paolo Bonzini 2017-01-02 15:22 ` [PATCH 1/5] kernel-doc: cleanup parameter type in function-typed arguments Paolo Bonzini 2017-01-02 15:22 ` [PATCH 2/5] kernel-doc: strip attributes even if they have an argument Paolo Bonzini 2017-01-02 15:22 ` [PATCH 3/5] kernel-doc: include parameter type in docbook output Paolo Bonzini 2017-01-02 15:22 ` [PATCH 4/5] kernel-doc: make member highlighting available in all backends Paolo Bonzini 2017-01-02 15:22 ` [PATCH 5/5] kernel-doc: make highlights more homogenous for the various backends Paolo Bonzini 2017-01-03 9:57 ` [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Jani Nikula 2017-01-04 15:13 ` Paolo Bonzini 2017-01-04 15:40 ` Jani Nikula 2017-01-04 22:06 ` Jonathan Corbet 2017-01-23 13:42 ` Markus Heiser 2017-01-23 13:58 ` Paolo Bonzini 2017-01-23 14:38 ` Markus Heiser
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).