Re: #774: [PATCH] avoid early exit when acting on some non-versioned files

Branko Čibej <brane@xbc.nu> writes:
> It's also practically impossible to maintain such documentation. Any new
> error code produced by a function would have to be documented in all its
> callers, recursively. I've lived on projects that expected things to be
> documented like that, and I haven't seen a single case where this rule
> was consistenly adhered to. Bits rot much, much faster if you impose an
> impossible rule.

Yes, that's why I at least have never really pressed that we do it --
I couldn't figure out how we'd maintain it.

(I assume by "such documentation" you mean documentation in which all
error codes are documented, not just the ones being depended on.)

By the way, Eric, I just remembered the other half of the reason for
the current practice: if the depended-on errors are mentioned in the
callee's doc string, then anyone changing the implementation of the
callee knows what behaviors must not change -- at least, not without
the callers changing too.

> Now, if we had a script that automated such docs, things would be different.

Whoo. Yeah, that would be neat! The background color in my editor is
blue, like the sky where this feature is found :-).

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Tue Apr 29 20:16:24 2003