[U-Boot] a couple notes on kernel-doc in u-boot

[Robert P. J. Day]

  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/Documentation/kernel-doc-nano-HOWTO.txt

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

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================