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