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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
