Re: [eclipse-dev] The ongoing migration saga

[Jim des Rivieres <Jim_des_Rivieres@xxxxxxxxxx>]

> I have previously noted that the Eclipse API is rather notorious for
> seldom documenting when null arguments are or are not accepted. 

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

In the particular case you mention of TreeViewer.Reveal, the spec does not 
allow the element to be null. In the course of fixing a viewer related bug 
(https://bugs.eclipse.org/bugs/show_bug.cgi?id=45253) caused by null being 
passed, the implementation was changed to include an up-front null check. 
This appears to have caught your code, which was passing null and counting 
on it to be ignored.

The implementation of the API method should have been rejected null 
parameters all along, so that client code could not accidentally get away 
replying on more than is promised.

---jim





"Bob Foster" <bob@xxxxxxxxxxxx>
Sent by: eclipse-dev-admin@xxxxxxxxxxx
12/11/2003 12:45 PM
Please respond to eclipse-dev

 
        To:     <eclipse-dev@xxxxxxxxxxx>
        cc: 
        Subject:        [eclipse-dev] The ongoing migration saga



Now that I have a version that "works" with M5 a couple of users have
reported bugs that look very much like API that was previously accepting
null arguments is no longer. The clearest case of this is in TreeViewer
reveal(), which I was clearly calling in prior releases with null and now
runs afoul of an assertion.

I have previously noted that the Eclipse API is rather notorious for 
seldom
documenting when null arguments are or are not accepted. This forces the
user to read the code to discover the allowed argument range, and then of
course when the code changes later it may be claimed that the caller is
depending on "internal details". I'd like to head this off in the general
case by asking, what the heck else _could_ one depend on, with 
documentation
like:

@param element the element

In this particular case, reveal() was clearly coded to accept null in 2.1.
Adding the assertion changed the API, actually worse than changing 
argument
types because it is not detected by the compiler.

Not to pick on this one little change; if it is an outlier I apologize to
the developer involved. But there is a lot of code getting "cleaned up" at
the moment, and I'm betting if there is one case there are a hundred. 
Could
Eclipse please supply, as part of your migration docs, a list of all cases
where assertions have been added where there were none before? And how 
about
updating the javadoc at the same time, so the API finally gets documented?

Thanks.

Bob Foster

_______________________________________________
eclipse-dev mailing list
eclipse-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe 
from this list, visit
http://dev.eclipse.org/mailman/listinfo/eclipse-dev