Re: [Qemu-devel] [PATCH] include/qemu: Add documentation to functions in include/qemu/id.h

[Markus Armbruster]

Veronia Bahaa <address@hidden> writes:

> Add documentation to the functions id_generate and id_wellformed in 
> include/qemu/id.h
>
> Signed-off-by: Veronia Bahaa <address@hidden>
> ---
>  include/qemu/id.h |   23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
>
> diff --git a/include/qemu/id.h b/include/qemu/id.h
> index 40c7010..7bbcdc0 100644
> --- a/include/qemu/id.h
> +++ b/include/qemu/id.h
> @@ -7,7 +7,30 @@ typedef enum IdSubSystems {
>      ID_MAX      /* last element, used as array size */
>  } IdSubSystems;
>  
> +/**
> + * id_generate: Generates an ID of the form PREFIX SUBSYSTEM NUMBER
> + *  where:
> + *
> + *  - PREFIX is the reserved character '#'
> + *  - SUBSYSTEM identifies the subsystem creating the ID
> + *  - NUMBER is a decimal number unique within SUBSYSTEM.
> + *
> + *    Example: "#block146"
> + *
> + * Returns the generated id string for the subsystem
> + *
> + * @id: the subsystem to generate an id for
> + */

This copies the function comment from the definition.  Not a good idea,
because the copies are prone to get inconsistent over time.

There are two schools of thought on where to put function comments: next
to the definition, or next to a declaration.

The latter school argues that it produces headers that do double-duty as
interface documentation.

The former school points out that separating the function comment from
the actual function reduces the chance of the function comment to stay
correct.  Also, editors worth using can take you to the definition
quickly.

id.c and id.h conform to the the latter school.  Changeable, but change
requires justification.

>  char *id_generate(IdSubSystems id);
> +
> +/**
> + * id_wellformed: checks that an id starts with a letter
> + *  followed by numbers, digits, '-','.', or '_'
> + *
> + * Returns %true if the id is well-formed
> + *
> + * @id: the id to be checked
> + */
>  bool id_wellformed(const char *id);
>  
>  #endif

Here's my try:

/*
 * Is @id a well-formed identifier?
 *
 * Well-formed identifiers consists only of letters, digits, '-', '.'
 * and '_', starting with a letter.
 */