[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
pgpcmuZKwoAXR.pgp
Description: PGP signature
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- Format of comments,
Neal H Walfield <=