hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Roland Weber <http-as...@dubioso.net>
Subject Re: JavaDocs and RFC
Date Thu, 15 Feb 2007 17:37:41 GMT
Hi Odi,

> I have the same opinion as Oleg about the issue. Quoting makes it
> absolutely clear which version of the spec was used for the
> implementation. If you use links they will become unavailable at some
> point and may be hard to restore!

Stating the RFC number is just as clear, and the hyperlink
around it are just meant as a convenience. I see the JavaDocs
as something that users will browse as well as developers. It
is not exactly helpful for a user to see two pages of BNF grammar
and associated narrative about chunked encoding in the JavaDocs,
replicated for both Input and Output stream implementation.
We could put such quotes into non-JavaDocs, but there still
remains one issue: our quotes are second hand information.
Somebody who wants to verify whether the implementation is correct
still needs to look up the offical version of the RFC and check
that the quoted text is correct.

The occasion which triggered my mail was the HttpExpectationVerifier
interface. I've had another look at it, and in that case it is
really helpful for the implementor of the interface to be made
aware of the requirements. I do not object to short quotes where
they are helpful to the user.

Let's handle this on a case by case basis when I review the
JavaDocs. It'll be a while though :-)

cheers,
  Roland


---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org


Mime
View raw message