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:19:42 GMT

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. 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)
> 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 :). Moreover, we will need a
> number of native English speakers who will volunteer to write the docs
> for us.
> So, what do we do with the methods that act exactly as specified?

I think that there's no point rewriting the standard JavaDoc for J2SE. 
    That's the spec.  If we want to fix it, we engage w/ the EG.  That 
said, we probably do have info for our implementation of the standard 
API, and javadoc is the right way to capture it.

So I think that the urls to the Sun javadoc is the right way to do it, 
because then it's easy for someone to browse our "implementation notes" 
in the standard format, with ease of access to get to the standard code, 
and also be able to see information that we have for our specific impl.


View raw message