[U-Boot] [PATCH 2/4] tools/env: javadoc for fw_printenv, fw_getenv and fw_parse_script

[Andreas Fenkart]

Hi Simon,

I sent out a v2 of this series, you should have received by now. Some
comments in the context:

2016-07-09 16:39 GMT+02:00 Simon Glass <sjg at chromium.org>:
> On 27 June 2016 at 16:06, Andreas Fenkart
> <andreas.fenkart at digitalstrom.com> wrote:

[snip]

>> +/**
>> + * fw_printenv - print one or several environment variables
>
> We normally add function brackets:

Hmm, I wonder what actually is used, since it's neither javadoc nor kernel-doc

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
http://www.mjmwired.net/kernel/Documentation/kernel-doc-nano-HOWTO.txt

For javadoc we would have to use @param <arg> keyword instead of the
shorter @arg used in the patch. But kernel-doc does not support
@return/@returns, it requires a 'Return:' section.

I verified the markup using:
./scripts/kernel-doc -html -v tools/env/fw_env.h

This was just for convenience, since the script comes with the source.
I can switch to whatever format is preferred.

>    fw_printenv() - print ...
>
>> + *
>> + * @argc  number of variables names to be printed, print all if 0
>> + * @argv  array of variable names to be printed
>> + * @value_only  do not repeat the variable name, only print the value,
>> + *          only one variable allowed with this option, argc must be 1
>> + * @opts  encryption key, configuration file, defaults are used if NULL
>
> @returns

$ grep -re  '\W at return\W' * | wc -l
1280

$ grep -re  '\W at returns\W' * | wc -l
12

javadoc uses @return

Is there a tool that processes the existing documentation markup,
probably it's not kernel-doc since it doesn't know the @return keyword

[snip]

/Andi