On 07/17/2016 04:12 PM, Simon Glass wrote:
+Marek
Hi Andreas,
On 16 July 2016 at 09:35, Andreas Fenkart afenkart@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@chromium.org:
On 27 June 2016 at 16:06, Andreas Fenkart andreas.fenkart@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.htm... 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@return\W' * | wc -l 1280
$ grep -re '\W@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.