Coding convention of function header comments

Coding convention of function header comments

[Hua Zhong]

Hi:

Sorry maybe this is not the best place to ask, but recently I need to come
up with coding conventions regarding function header comments which explain
the usage of functions (meaning of parameters, etc).  <linux/list.h> has sth
like this:

/**
 * list_add - add a new entry
 * @new: new entry to be added
 * @head: list head to add it after
 *
 * Insert a new entry after the specified head.
 * This is good for implementing stacks.
 */
static __inline__ void list_add(struct list_head *new, struct list_head
*head)
{
 __list_add(new, head, head->next);
}

Similar to Java.  I want to ask that (1) is this a well-known convention or
was just invented (informally) by someone here (e.g., Linus?)?  Where can I
find the documentation about this convention? (2) can anyone point me to the
URL of similar well-known coding conventions (except the Java one)?

Many thanks.

-Hua

Re: Coding convention of function header comments

[Alan Cox]

> /**
>  * list_add - add a new entry
>  * @new: new entry to be added
>  * @head: list head to add it after
>  *
>  * Insert a new entry after the specified head.
>  * This is good for implementing stacks.
>  */
> static __inline__ void list_add(struct list_head *new, struct list_head
> *head)
> {
>  __list_add(new, head, head->next);
> }
> 
> Similar to Java.  I want to ask that (1) is this a well-known convention or
> was just invented (informally) by someone here (e.g., Linus?)?  Where can I
> find the documentation about this convention? (2) can anyone point me to the
> URL of similar well-known coding conventions (except the Java one)?

Ok firstly - yes its a straight rip off of the java one. The history is
something like. Gnome needed a format for this, so Michael Zucchi (I
believe) wrote up a hideous perl hack. Miguel de Icaza couldn't get the
format right so it was extended with a free form body. 

Its documented in Documentation/kernel-doc-nano-HOWTO.txt

We do need to improve it to mark up structures, and also to actually
finish the job.