You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hc.apache.org by Roland Weber <ht...@dubioso.net> on 2007/02/14 20:25:11 UTC
JavaDocs and RFC
Hi Oleg,
there are a few places where our JavaDocs include more or less
verbatim quotes from RFCs, including context free grammars. I
don't think that's a good idea. For one there is the copyright
question. But I've also seen some quotes from obsolete RFCs
in code that probably hasn't changed much since HC 2.0.
If a particular piece of code refers to a specific part of an
RFC, we should give a short description of the purpose and
reference the RFC down to the section, but not copy the text
of the RFC into the JavaDocs. www.rfc.net has nice formatted
versions of RFCs where we can even hyperlink to sections.
What do you think?
cheers,
Roland
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: JavaDocs and RFC
Posted by Roland Weber <ht...@dubioso.net>.
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
Re: JavaDocs and RFC
Posted by Ortwin Glück <od...@odi.ch>.
Roland,
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!
I guess we can use the RFC documents in citations. Their copyright is
very open:
"This document [...] may be [...] copied [...] without restriction of
any kind provided that the above copyright notice and this paragraph are
included on all such copies [...]"
To be sure we should probably reproduce their (The Internet Society)
copyright statement in the documentation. The legal aspect should be
properly discussed on the legal mailing list, however.
Odi
Roland Weber wrote:
> Hi Oleg,
>
> there are a few places where our JavaDocs include more or less
> verbatim quotes from RFCs, including context free grammars. I
> don't think that's a good idea. For one there is the copyright
> question. But I've also seen some quotes from obsolete RFCs
> in code that probably hasn't changed much since HC 2.0.
> If a particular piece of code refers to a specific part of an
> RFC, we should give a short description of the purpose and
> reference the RFC down to the section, but not copy the text
> of the RFC into the JavaDocs. www.rfc.net has nice formatted
> versions of RFCs where we can even hyperlink to sections.
>
> What do you think?
>
> cheers,
> Roland
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
>
--
[web] http://www.odi.ch/
[blog] http://www.odi.ch/weblog/
[pgp] key 0x81CF3416
finger print F2B1 B21F F056 D53E 5D79 A5AF 02BE 70F5 81CF 3416
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
Re: JavaDocs and RFC
Posted by Oleg Kalnichevski <ol...@apache.org>.
On Wed, 2007-02-14 at 20:25 +0100, Roland Weber wrote:
> Hi Oleg,
>
> there are a few places where our JavaDocs include more or less
> verbatim quotes from RFCs, including context free grammars. I
> don't think that's a good idea. For one there is the copyright
> question. But I've also seen some quotes from obsolete RFCs
> in code that probably hasn't changed much since HC 2.0.
> If a particular piece of code refers to a specific part of an
> RFC, we should give a short description of the purpose and
> reference the RFC down to the section, but not copy the text
> of the RFC into the JavaDocs. www.rfc.net has nice formatted
> versions of RFCs where we can even hyperlink to sections.
>
> What do you think?
>
Hi Roland,
To me RFCs are _the_ ultimate reference for lots of protocol level
components, and besides we are building HTTP components to conform to a
very _specific_ set of RFCs, so I personally do not see an issue with
quoting RFCs verbatim. Feel free to change / improve Javadocs as you
find appropriate, though.
Oleg
> cheers,
> Roland
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: httpcomponents-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: httpcomponents-dev-help@jakarta.apache.org