Re: Coding convention of function header comments

Alan Cox (alan@lxorguk.ukuu.org.uk)
Wed, 15 Aug 2001 23:00:31 +0100 (BST)


> /**
> * 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.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/