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

[Marek Vasut]

On 07/17/2016 04:12 PM, Simon Glass wrote:
> +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.

I'm not sure what the question is, I didn't manage to extrapolate it 
from the previous discussion -- but kerneldoc is the preferred doc 
format for u-boot.


-- 
Best regards,
Marek Vasut