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

From: Paolo Bonzini
Date: Mon Jan 02 2017 - 10:23:04 EST

Next message: Paolo Bonzini: "[PATCH 3/5] kernel-doc: include parameter type in docbook output"
Previous message: Guenter Roeck: "Re: [PATCH v3 2/2] watchdog: introduce CONFIG_WATCHDOG_OPEN_TIMEOUT"
In reply to: Paolo Bonzini: "[PATCH 2/5] kernel-doc: strip attributes even if they have an argument"
Next in thread: Paolo Bonzini: "[PATCH 3/5] kernel-doc: include parameter type in docbook output"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

$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@xxxxxxxxxx>
---
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 = '\&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, "\$1"],
[$type_func, "\$1"],
+ [$type_enum_xml, "\$1"],
[$type_struct_xml, "\$1"],
+ [$type_typedef_xml, "\$1"],
+ [$type_union_xml, "\$1"],
[$type_env, "\$1"],
[$type_param, "<tt>\$1</tt>"],
- [$type_member_xml, "<tt>\$1\$2\$3</tt>"]
+ [$type_member_xml, "<tt>\$1\$2\$3</tt>"],
+ [$type_fallback_xml, "\$1"]
);
my $local_lt = "\\\\\\\\lt:";
my $local_gt = "\\\\\\\\gt:";
@@ -245,10 +253,14 @@ my $blankline_html = $local_lt . "p" . $local_gt; # was ""
my @highlights_html5 = (
[$type_constant, "\$1"],
[$type_func, "\$1"],
+ [$type_enum_xml, "\$1"],
[$type_struct_xml, "\$1"],
+ [$type_typedef_xml, "\$1"],
+ [$type_union_xml, "\$1"],
[$type_env, "\$1"],
[$type_param, "\$1]"],
- [$type_member_xml, "\$1\$2\$3"]
+ [$type_member_xml, "\$1\$2\$3"],
+ [$type_fallback_xml, "\$1"]
);
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

Next message: Paolo Bonzini: "[PATCH 3/5] kernel-doc: include parameter type in docbook output"
Previous message: Guenter Roeck: "Re: [PATCH v3 2/2] watchdog: introduce CONFIG_WATCHDOG_OPEN_TIMEOUT"
In reply to: Paolo Bonzini: "[PATCH 2/5] kernel-doc: strip attributes even if they have an argument"
Next in thread: Paolo Bonzini: "[PATCH 3/5] kernel-doc: include parameter type in docbook output"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]