[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [eclipse-dev] The ongoing migration saga
|
>> 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).
Patrick Baker wrote:
> 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.
The Eclipse project's javadoc conventions
http://dev.eclipse.org/javadoc.html
follow Sun's Requirements for Writing Java API Specifications in most
regards
http://java.sun.com/products/jdk/javadoc/writingapispecs/index.html
The section on method specifications in the Sun document puts it this way:
4. Null Argument Values - For each reference type argument, specify the
behavior when null is passed in. See two examples. NOTE: If possible,
document the general null argument behavior at the package or class level,
such as causing a java.lang.NullPointerException to be thrown. Deviations
from this behavior can then be documented at the method level.
5. Range of Return Values - Specify the range of possible return values,
including where the return value may be null. See example.
> 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).
There is one in the help system:
Eclipse Platform Plug-in Developer Guide > Reference > Other reference
information > Platform API Rules of Engagement
(Or do a help search for "API" - it's the first hit.)
But you have a good point that the doc would be improved is it was more
prominent. I've entered
https://bugs.eclipse.org/bugs/show_bug.cgi?id=48605 on your behalf.
---jim
