it's been a while since i've messed with kernel-doc so i've
forgotten a lot of it. i recall the admonition that you can't define a
Return: section as a list, because:
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
NOTE 2: If the descriptive text you provide has lines that begin
with some phrase followed by a colon, each of those phrases will be
taken as a new section heading, which means you should similarly
try to avoid text like:
Return:
0: cool
1: invalid arg
2: out of memory
every line of which would start a new section. Again, probably not
what you were after.
not surprisingly, there's still a fair bit of that sort of thing in
the kernel tree, like this from drivers/misc/genwqe/card_ddcb.c:
/**
* __genwqe_wait_ddcb(): Waits until DDCB is completed
* @cd: pointer to genwqe device descriptor
* @req: pointer to requsted DDCB parameters
*
* The Service Layer will update the RETC in DDCB when processing is
* pending or done.
*
* Return: > 0 remaining jiffies, DDCB completed
* -ETIMEDOUT when timeout
* -ERESTARTSYS when ^C
* -EINVAL when unknown error condition
*
* When an error is returned the called needs to ensure that
* purge_ddcb() is being called to get the &req removed from the
* queue.
*/
so i'm simply assuming that's not going to work properly.
but i just noticed this in drivers/acpi/property.c:
/**
* acpi_data_get_property - return an ACPI property with given name
* @data: ACPI device deta object to get the property from
* @name: Name of the property
* @type: Expected property type
* @obj: Location to store the property value (if not %NULL)
*
* Look up a property with @name and store a pointer to the resulting ACPI
* object at the location pointed to by @obj if found.
*
* Callers must not attempt to free the returned objects. These objects will be
* freed by the ACPI core automatically during the removal of @data.
*
* Return: %0 if property with @name has been found (success),
* %-EINVAL if the arguments are invalid,
* %-EINVAL if the property doesn't exist,
* %-EPROTO if the property value type doesn't match @type.
*/
what's with those "%" symbols in the Return section? do they have
some special value? i don't recall those.
so *is* there a way to get that bullet list effect these days?
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
