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

[Simon Glass]

+Marek

Hi Andreas,

On 16 July 2016 at 09:35, Andreas Fenkart <afenkart at gmail.com> wrote:
> 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

I'm (hopefully) following instructions from Marek who may have more
info on this. I believe it is docbook (make pdfdocs), but only a few
files are included at present.

Regards,
Simon