You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by Mark Thomas <ma...@apache.org> on 2011/06/01 10:57:52 UTC
Re: Outdated Servlet 3.0 Javadocs available on tomcat.apache.org
On 31/05/2011 21:48, Christopher Schultz wrote:
> All,
>
> I just went to check something in the 3.0 Servlet API and the most
> convenient place I've found is on the Tomcat site. Unfortunately, it
> looks like it's out of date:
>
> http://tomcat.apache.org/tomcat-7.0-doc/servletapi/index.html
>
> Many of the 3.0 classes and methods are left undocumented (for example
> ServletContext.addFilter).
>
> http://tomcat.apache.org/tomcat-7.0-doc/servletapi/javax/servlet/ServletContext.html#addFilter%28java.lang.String,%20java.lang.Class%29
>
> It just looks like the API docs up there are from an old publication of
> the spec. The currently-available javadocs from the spec page are
> complete with comments, etc.
Those comments are part of CDDL licensed source code. My reading of
http://www.apache.org/legal/resolved.html#category-b is that we can't
copy the comments directly into our source code.
> What's the best way to update those javadocs? I'd be happy to do it.
Options that come to mind:
a) do nothing
b) add @see www.oracle.com tags where there are gaps
c) fill in the blanks based on our understanding of what the contract is
for each method
pid did provide some patches for this but there are still a lot of blanks.
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Outdated Servlet 3.0 Javadocs available on tomcat.apache.org
Posted by Mark Thomas <ma...@apache.org>.
On 01/06/2011 17:36, Tim Funk wrote:
> Doh - Older specs had the javadocs. I never scrolled to the end to notice it
> missing from the current spec.
Even then I don't think direct copying is permitted by the license you
have to agree to download the spec but I admit I haven't looked at it
too carefully.
Mark
>
> -Tim
>
> On Wed, Jun 1, 2011 at 11:29 AM, Christopher Schultz <
> chris@christopherschultz.net> wrote:
>
>> Tim,
>>
>> On 6/1/2011 8:35 AM, Tim Funk wrote:
>>> Is the PDF of the spec which is downloadable up to date with respect to
>>> comments?
>>
>> The version of the PDF I'm looking at (3.0 Final, 1434610 bytes, dated
>> 10 December 2009) does not include the javadoc at all... it does include
>> some documentation of certain methods... I have only done a casual
>> reading at this point.
>>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
Re: Outdated Servlet 3.0 Javadocs available on tomcat.apache.org
Posted by Tim Funk <fu...@apache.org>.
Doh - Older specs had the javadocs. I never scrolled to the end to notice it
missing from the current spec.
-Tim
On Wed, Jun 1, 2011 at 11:29 AM, Christopher Schultz <
chris@christopherschultz.net> wrote:
> Tim,
>
> On 6/1/2011 8:35 AM, Tim Funk wrote:
> > Is the PDF of the spec which is downloadable up to date with respect to
> > comments?
>
> The version of the PDF I'm looking at (3.0 Final, 1434610 bytes, dated
> 10 December 2009) does not include the javadoc at all... it does include
> some documentation of certain methods... I have only done a casual
> reading at this point.
>
Re: Outdated Servlet 3.0 Javadocs available on tomcat.apache.org
Posted by Christopher Schultz <ch...@christopherschultz.net>.
Tim,
On 6/1/2011 8:35 AM, Tim Funk wrote:
> Is the PDF of the spec which is downloadable up to date with respect to
> comments?
The version of the PDF I'm looking at (3.0 Final, 1434610 bytes, dated
10 December 2009) does not include the javadoc at all... it does include
some documentation of certain methods... I have only done a casual
reading at this point.
> I don't think the pdf version of the spec is CDDL ... but it may
> have other conditions on it.
There does not appear to be a specific license mentioned in the PDF,
though it does limit what the reader can do with it. It says that
"excerpting brief portions of the Specification" is acceptable, but I
suspect that copying lots of text like that is a no-no because you can
only do it "provided that such excerpts do not in the aggregate
constitute a significant portion of the Specification". The javadoc is a
lot of stuff. One needs to consider whether the javadoc itself is part
of the specification or not. :(
Downloading both the PDF and the Javadoc ZIP archive require that you
accept the SLA which can be found here
(http://download.oracle.com/otndocs/jcp/servlet-3.0-fr-oth-JSpec/servlet-3.0-fr-oth-JSpec-license.html)
and appears to be the same agreement as included at the top of the PDF
version of the specification.
Mark, I never saw anything about the CDDL while poking around the Oracle
download site. If we use the Oracle-provided Javadoc ZIP archive rather
than generating the Javadocs from the CDDL source, might that be
acceptable? I'm certainly not asking for a legal opinion, here, just
what your general sense is of these things.
It's frustrating that Oracle doesn't just publish the Servlet API
javadocs on it's own web site :(
-chris
Re: Outdated Servlet 3.0 Javadocs available on tomcat.apache.org
Posted by Tim Funk <fu...@apache.org>.
Is the PDF of the spec which is downloadable up to date with respect to
comments? I don't think the pdf version of the spec is CDDL ... but it may
have other conditions on it. If the PDF version of the spec is up to date,
someone might be able to copy from the PDF and paste into the javadocs and
add the correct formatting.
-Tim
On Wed, Jun 1, 2011 at 4:57 AM, Mark Thomas <ma...@apache.org> wrote:
>
> Those comments are part of CDDL licensed source code. My reading of
> http://www.apache.org/legal/resolved.html#category-b is that we can't
> copy the comments directly into our source code.
>
>