harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dalibor Topic <robi...@kaffe.org>
Subject Re: Writing JavaDoc
Date Tue, 10 Jan 2006 16:31:41 GMT
Stefano Mazzocchi wrote:
> 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.
> 

I think that's a feature, too, I am sorry if it sounded otherwise.
Thanks for correcting my mistake.

I was under the wrong impression that the specification itself was
developed outside the RI, and they were kept in sync as an indirect
feature of the development model chosen (spec maintained as embedded
javadoc, rather than as, say, an external Microsoft Word document). I'm
glad to hear that I am wrong.

cheers,
dalibor topic

Mime
View raw message