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.
geir
