bug-hurd
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Format of comments


From: Neal H Walfield
Subject: Format of comments
Date: Sat, 30 Dec 2000 19:42:39 -0500
User-agent: Mutt/1.2.5i

I am curious what should and should not be commented on and how the
comments should be formatted.  My question derives from the public
interface documented in netfs.h.  I believe that each function should
have two sections, the description and the pre/post conditions.
However, diskfs only has descriptions and the conditions within the
prose.

For instance:
/* The user must define this function.  Attempt to create a file named
   NAME in DIR (which is locked) for USER with MODE.  Set *NP to the
   new node upon return.  On any error, clear *NP.  *NP should be
   locked on success; no matter what, unlock DIR before returning.  */
error_t netfs_attempt_create_file (struct iouser *user, struct node *dir,
                                   char *name, mode_t mode, struct node **np);

or

/* The user must define this function.  Attempt to create a file named
   NAME in DIR for USER with MODE.  Set *NP to the new node upon return.
   On any error, clear *NP.

   DIR must be locked on entry and unlocked on exit.  If successful,
   *NP must be locked.  */
error_t netfs_attempt_create_file (struct iouser *user, struct node *dir,
                                   char *name, mode_t mode, struct node **np);

The latter seems to me to be more explicit.

-Neal

-- 
Neal H Walfield
University of Massachusetts at Lowell
neal@walfield.org or neal@cs.uml.edu

Attachment: pgpcmuZKwoAXR.pgp
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]