[AFS3-std] Re: AFSVol GetSizeV2 draft

[David Boyes]

>=20
> The return code for successful return from an Rx RPC is zero.  This is=20
> inherent in the protocol, because a successful return is represented=20
> differently from any error return. =20

So what harm is done to specify that outside of an implementation? There ar=
en't any other docs, so what's your problem here?

> Having a constant for this might look=20
> pretty, but pretending it can't th be other than zero is silly.
>=20

It may be silly but it's documenting something no one has ever bothered to =
write down so far outside the code of an implementation. As you bluntly com=
mented elsewhere, this is documenting a protocol, not annotating a specific=
 implementation. This removes an ambiguity in the protocol specification. B=
eyond that, whether we use a constant name or not is really a personal pref=
erence. *I* happen to think it makes it easier on the implementer to have O=
NE defined symbolic value that means the same thing in the entire specifica=
tion but I'll take argument on that.=20

Short version: IMHO allowing something to be assumed is bad practice for a =
specification.=20

You know, the more we wiggle on this hook, the more it seems necessary to g=
o back and actually document what the existing stuff does. That would circu=
mvent this kind of discussion and perhaps we might be able to discuss chang=
es more productively.

> BTW, David, it would be really helpful if in your comments you referred t=
o=20
> sections of the document (its logical structure) rather than only to=20
> specific line numbers in a particular representation.  For example...
>=20

I was using the output of idnits, which provides nice line numbers. I find =
that to be a useful tool to have everyone looking at the same document...

> My web browser doesn't show line numbers, so it's very hard for me to=20
> figure out what "line 162" is here and thus to figure out what David is=20
> commenting on.

See above. Idnits will insert the line numbers in it's output for any of th=
e formats it supports, including displaying it in the browser.=