first, what is the recommended location for kernel-doc -- the header files or the source files -- because i'm currently perusing lib/libfdt/*.c, and the kernel-doc seems to be scattered across both locations. does u-boot have a preference?
next. some of the kernel-doc is incorrect or invalid. consider the following snippet in libfdt.h:
/** * fdt_first_subnode() - get offset of first direct subnode * * @fdt: FDT blob * @offset: Offset of node to check * @return offset of first subnode, or -FDT_ERR_NOTFOUND if there is none */
the kernel-doc guide at
http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Document...
makes it clear:
"Avoid putting a spurious blank line after the function name, or else the description will be repeated!"
next, i'm pretty sure the following from fdt_region.c is incorrect:
/** * fdt_add_region() - Add a new region to our list * * The region is added if there is space, but in any case we increment the * count. If permitted, and the new region overlaps the last one, we merge * them. * * @info: State information * @offset: Start offset of region * @size: Size of region */
since the parameter lines should *immediately* follow the function name line, as in:
Example kernel-doc function comment:
/** * foobar() - short function description of foobar * @arg1: Describe the first argument to foobar. * @arg2: Describe the second argument to foobar. * One can provide multiple line descriptions * for arguments. * ... etc etc ...
finally, trying to list the possible return values this way is wrong:
/** * fdt_check_header - sanity check a device tree or possible device tree * @fdt: pointer to data which might be a flattened device tree * * fdt_check_header() checks that the given buffer contains what * appears to be a flattened device tree with sane information in its * header. * * returns: * 0, if the buffer appears to contain a valid device tree * -FDT_ERR_BADMAGIC, * -FDT_ERR_BADVERSION, * -FDT_ERR_BADSTATE, standard meanings, as above */
for the following reason:
"NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in:
Return: 0 - cool 1 - invalid arg 2 - out of memory
this will all run together and produce:
Return: 0 - cool 1 - invalid arg 2 - out of memory
anyway, just a few observations.
rday