Re: [PATCH] libnetfs documentation / audit

[Marcus Brinkmann]

Hi Neal,

On Fri, Dec 29, 2000 at 01:31:15PM -0500, Neal H Walfield wrote:
> I have audited most of libnetfs and added a lot of documentation to
> hurd/netfs.h.  Most importantly in the latter case is that I have
> explicitly outlined the locking protocol.

I have checked in most of your fixes as you provided them. However, let's
not set the errno in make-node. I also checked all callers of
netfs_make_node, and there is only one (nfs client) which doesn't deal, I
will fix that. The switch replacement for if (err && err != ...) I left out
because this is a common idiom in the Hurd source used elsewhere, too.

Apart from that, I made a lot of changes to your doc fixes in netfs.h.
We prefer to have two spaces before */, and full sentences in all cases.[1]
Also I chose to leave the original comment if it expressed the right thing
already, and abbreviate the locking protocol explanations by simply saying
"locked node NP" instead of what you wrote. What I found especially
confusing about your wording is that it sounded like an expectation, but it
is a guarantee made by the library, which is a caller of user contributed
functions in this case. I think I also simply dropped a two or three
explanations which weren't wrong, but also a little misplaced. Some of them
should go in full form into the Hurd info doc...

Please check yourself what I changed, and if you disagree, we can talk...

Thanks,
Marcus

[1] It's all in the gnu coding standards, *grin*

-- 
`Rhubarb is no Egyptian god.' Debian http://www.debian.org brinkmd@debian.org
Marcus Brinkmann              GNU    http://www.gnu.org    marcus@gnu.org
Marcus.Brinkmann@ruhr-uni-bochum.de
http://www.marcus-brinkmann.de