harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Geir Magnusson Jr <g...@pobox.com>
Subject Re: Writing JavaDoc
Date Fri, 13 Jan 2006 17:23:59 GMT


Tim Ellison wrote:
> Loenko, Mikhail Y wrote:
> 
>>Well, I'll try to summarize what we have
>>
>>There are three types of methods:
>>1. Methods that are part of the API, they are specified, they follow the
>>Sun's spec and we have nothing to add.
>>2. Methods that are part of the API and we have something to add (ex.:
>>the spec allows multiple behaviors).
>>3. Private methods or methods in com.*, org.* areas etc.
>>
>>I think we all agree that we have to document #3.
> 
> 
> I agree it is good practice to document the implementation of some
> non-API code for developers.

Some? why not all?

>  That documentation may or may not be
> JavaDoc.  For example, many people typically don't do a full JavaDoc
> comment for a private method.

Where would you put it?

> 
> 
>>But it's not clear for
>>me what we do with #1 and #2. I suggest discussing #1 first.
>>
>>We might want to omit documentation for #1 methods (though if the doc
>>describes all the methods except a single one - it might be confusing)
> 
> 
> Yes, that would be confusing.
> 
> 
>>or put there some standard words (like this method is implemented
>>according to the spec) and either do or don't provide a link to the
>>Sun's spec.
>>In the .java source files we might either skip javadoc comment (though
>>it would not improve code readability) or provide some standard words
>>for all such methods.
>>
>>Another option is to put reworded content of Sun's spec into the
>>documentation. I do not like this idea: if we say that our
>>implementation works according to our wording but not to the official
>>spec we might have problems with naming it Java (or we will have to say
>>"we implement our own spec that is semantically equivalent to Sun's
>>spec", which we'll have to prove first :).
> 
> 
> There is only one way that you can call an implementation Java(tm) --
> and that is to pass the JCK.
> 
> 
>>Moreover, we will need a
>>number of native English speakers who will volunteer to write the docs
>>for us.
> 
> 
> I sense that there is an underlying reason for the objection to writing
> JavaDoc ;-)  Do you really *want* URLs to Sun's website, or do you think
> that writing the doc will be too much effort, or ... ?  How about
> writing it in multiple languages if that's where our skills are?
> 
> AFAIK other projects that are implementing JSRs etc write the code and
> documentation to go alongside it rather than link to the reference.

How do you go "alongside"?

> Perhaps our friends involved with Classpath can give us an insight as to
> whether they regret writing JavaDoc, or whether they see it as a
> valuable part of the effort (assuming that they have written all the doc!).

Good idea.

> 
> 
>>So, what do we do with the methods that act exactly as specified?
> 
> 
> My view is that we document them using our own words, and go for quality
> documentation as well as quality implementation.

I agree that we should do that where it adds value, but I'm still a 
believer in also including the link to the standard javadoc, represented 
as such, because one has to believe that they were written by the 
experts in the field, and that there is a coherent 'domain specific 
jargon' used by those experts that one hopes is consistency throughout 
some given API domain.

That said, we should be providing *augmentation* to that that's 
important to our implementation.

geir

Mime
View raw message