Re: [PATCH] staging: sm750fb: format description of parameters the to kernel doc format

[Randy Dunlap <rdunlap@infradead.org>]

[-- Attachment #1: Type: text/plain, Size: 1367 bytes --]

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

[-- Attachment #2: kdoc_function --]
[-- Type: text/plain, Size: 1150 bytes --]

#! /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