[eclipse-dev] The ongoing migration saga

["Bob Foster" <bob@xxxxxxxxxxxx>]

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