harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: Writing JavaDoc
Date Tue, 10 Jan 2006 16:21:25 GMT
Dalibor Topic wrote:
> Zsejki Sorin Miklós wrote:
>> I have absolutely no experience with such things, but I'm wondering how
>> was this done with Tomcat, for example. They have the servlet API built
>> from their source code, and the javadoc seems to be word by word
>> identical to the specification. Is the servlet specification provided
>> under different terms than the J2SE documentation?
> 
> No. It's pretty much the same 'look but don't touch' thing.
> 
> Like any other contributor to Apache, the employees from servlet spec
> participating companies are free to publish their own stuff under their
> own licenses. So the official specs are released by whoever releases
> them (Sun? JCP? no idea ...) under a license granting fewer freedoms,
> than the ASLv2, for example.
> 
> The concidence that the official specs are identical to the comments in
> Tomcat's source code, is nothing more than that: a fortunate
> coincidence, facilitated by the way JavaDoc encourages implementation
> comments to be kept close to the source code, and easily extracted out
> of it, and by the willingness of people developing the spec to develop
> it in concert with the development of the reference implementation.
> 
> Conceptually, a specification and a reference implementation's comments
> are two pairs of shoes, and they do not have to be the same thing. In
> practice, I assume that they often enough are, as I'd doubt that formal
> methods have made huge inroads into J2SE specification development yet,
> unfortunately.

No, it's not a fortunate coincidence. The seed for the Apache Jakarta 
project were Tomcat, Ant and the Servlet API, that were donated (with 
ability to relicense) to the ASF and then the ASF decided to relicense 
them under the Apache License.

Therefore the fact that the javadocs are identical is a feature, not a bug.

-- 
Stefano.


Mime
View raw message