summaryrefslogtreecommitdiffstats
path: root/scripts
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab@s-opensource.com>2016-08-22 22:02:57 -0300
committerJonathan Corbet <corbet@lwn.net>2016-08-24 15:24:36 -0600
commit6d232c80158ae5a6fb497e0462d52c57c4459439 (patch)
treec3b317f0aba9b77e9155eb9fcb9547c82e14f0de /scripts
parentca7bfe2c8d9f3aee469a3a36110a95ebb511ee20 (diff)
downloadlinux-6d232c80158ae5a6fb497e0462d52c57c4459439.tar.gz
linux-6d232c80158ae5a6fb497e0462d52c57c4459439.tar.bz2
linux-6d232c80158ae5a6fb497e0462d52c57c4459439.zip
docs-rst: kernel-doc: better output struct members
Right now, for a struct, kernel-doc produces the following output: .. c:type:: struct v4l2_prio_state stores the priority states **Definition** :: struct v4l2_prio_state { atomic_t prios[4]; }; **Members** ``atomic_t prios[4]`` array with elements to store the array priorities Putting a member name in verbatim and adding a continuation line causes the LaTeX output to generate something like: item[atomic_t prios\[4\]] array with elements to store the array priorities Everything inside "item" is non-breakable, with may produce lines bigger than the column width. Also, for function members, like: int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num); It puts the name of the member at the end, like: int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read With is very confusing. The best is to highlight what really matters: the member name. is a secondary information. So, change kernel-doc, for it to produce the output on a different way: **Members** ``prios[4]`` array with elements to store the array priorities Also, as the type is not part of LaTeX "item[]", LaTeX will split it into multiple lines, if needed. So, both LaTeX/PDF and HTML outputs will look good. It should be noticed, however, that the way Sphinx LaTeX output handles things like: Foo bar is different than the HTML output. On HTML, it will produce something like: **Foo** bar While, on LaTeX, it puts both foo and bar at the same line, like: **Foo** bar Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/kernel-doc2
1 files changed, 1 insertions, 1 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index ba081c7636a2..d225e178aa1b 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -2000,7 +2000,7 @@ sub output_struct_rst(%) {
($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;
$type = $args{'parametertypes'}{$parameter};
print_lineno($parameterdesc_start_lines{$parameter_name});
- print "``$type $parameter``\n";
+ print "``" . $parameter . "``\n";
output_highlight_rst($args{'parameterdescs'}{$parameter_name});
print "\n";
}