lkml.org 
[lkml]   [2019]   [Oct]   [16]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
SubjectRe: [PATCH] staging: sm750fb: format description of parameters the to kernel doc format
From
Date
On 10/16/19 6:29 PM, gbittencourt wrote:
> Hi Randy,
>
> On 10/16/19 10:25 PM, Randy Dunlap wrote:
>> Hi,
>>
>> On 10/16/19 6:18 PM, Gabriela Bittencourt wrote:
>>> Cluster comments that describes parameters of functions and create one
>>> single comment before the function in kernel doc format.
>> Good plan.
>>
>> How did you test this patch?
> I haven't test it. How can I do it?

Hm. There used to be a comment in a (now deleted) document named
Documentation/kernel-doc-nano-HOWTO.txt about how to test kernel-doc.

I took that comment and made a script from it.
I'll attach the script. It's easy to use, but it is made to test only
one function or struct or union or enum at a time.

You need to have a script named 'kernel-doc' in your PATH or you can
specify where the script is located by using
$ KERNDOC=path/to/scripts/kernel-doc kdoc_function _parameters_

Its usage is:
kdoc_function filename funcname [text|man|html|docbook|xml]

where funcname can be a function, struct, union, or enum name.
The output format can be any of those listed, but the default is "text".

Let me know if you have any questions or problems.

>>> Signed-off-by: Gabriela Bittencourt <gabrielabittencourt00@gmail.com>
>>> ---
>>>   drivers/staging/sm750fb/sm750_accel.c | 65 +++++++++++++++------------
>>>   1 file changed, 37 insertions(+), 28 deletions(-)


--
~Randy
#! /bin/sh
# from linux/Documentation/kernel-doc-nano-HOWTO.txt
# uses linux/scripts/kernel-doc or a copy of it (in $PATH).
# using "LANG=C or LC_ALL=C kdoc_function <prms>" can be useful.
# Can use "KERNDOC=<script_filename> kdoc_function <prms>" to vary
# which kernel-doc script is used.

verbose=
debug=
if [ "$KERNDOC" = "" ]; then
KERNDOC=kernel-doc
fi

# careful: must enter -v before -x:
if [ "$1" = "-v" ]; then
verbose="-v"
shift
fi
if [ "$1" = "-x" ]; then
debug="-x"
shift
fi

file="$1"
fn="$2"
# fmt can be "text|man|html|docbook|xml" (default is "text")
# docbook produces xml
fmt="$3"
if [ x$3 = x ]; then
fmt="text"
fi

if [ "$2" = "" ]; then
echo "usage: kdoc_function filename funcname [text|man|html|docbook|xml]"
exit 1
fi

case $fmt in
man)
$KERNDOC $verbose $debug -man -function $fn $file | nroff -man | less
;;
html)
$KERNDOC $verbose $debug -html -function $fn $file >kerneldoc.html
echo "see kerneldoc.html"
;;
docbook|xml)
$KERNDOC $verbose $debug -docbook -function $fn $file >kerneldoc.xml
echo "see kerneldoc.xml"
;;
*)
$KERNDOC $verbose $debug -text -function $fn $file | less
;;
esac
\
 
 \ /
  Last update: 2019-10-17 03:52    [W:0.297 / U:0.112 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site