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
[EMAIL PROTECTED] or [EMAIL PROTECTED]
PGP signature
