Re: [eclipse-dev] The ongoing migration saga

["Patrick Baker" <pbaker@xxxxxxxxxxxx>]

Jim sed:
>
> The Eclipse API follows the standard Java practice of explicitly
> specifying where null is allowed for all API method parameters, return
> results, and field (and also elements of arrays or collections). If the
> spec does not *explicitly* state that null is allowed, it is *never*
> allowed. The results of passing null are generally left unspecified
> (implementation might throw some kind of runtime exception, or might not).
>

What "standard" are you referring to? It is useless to claim that a practice
is "standard" without letting us know where we can go to find out what the
"standard" is.

A google search with "java javadoc convention null" or "javadoc style guide
null" makes it clear that different people/groups have different opinions
and "standard" conventions on issues like this. I can't find anything on
this in Gosling, Steele and Joy (The Java Language Specifictaion) which
might be considered a source for a "standard".

Here is an IBM web page that suggests the opposite convention than that
described above.

http://www-106.ibm.com/developerworks/library/j-jtp0821.html#heading4

There should be an Eclipse javadoc style guide which ships with the Eclipse
docs that desribes these things so that we know how to read the Eclipse
docs. In fact, I consider it a documentation error not to include this.
(Apologies if there is actually one already, but I haven't found it).

Apologies if this sounds like a rant, it isn't intended to be one. I really
think that the quality of the documentation good be improved from these
sorts of suggestions.

cheers!

-----------------------------------------------
Patrick Baker
Stilo Corporation
pbaker@xxxxxxxxxxxx

"Hail, twin companionship, children of Mars."

This message, including any attachments, is for the sole use of the
intended recipient(s) and may contain confidential and privileged
information. Any unauthorized review, use, disclosure, copying, or
distribution is strictly prohibited. If you are not the intended
recipient(s) please contact the sender by reply email and destroy
all copies of the original message and any attachments.