Re: jdiff.sh (BETA)

[Giannis Georgalis]

Tom Tromey <address@hidden> writes:

> >>>>> "Giannis" == Giannis Georgalis <address@hidden> writes:
> 
> Giannis> Yes, however jdiff.sh completely ignores the throws clause
> Giannis> and instead parses the javadoc comments above the class
> Giannis> definition.
> 
> This isn't always desirable.  Sometimes Sun documents unchecked
> exceptions; we aren't required to declare these.  Even documenting
> them may be suspect.

You don't have to declare unchecked exceptions, as long as you
document them in your code (with the @throws *or* @exception tag).
The very first version of jdiff, only checked the methods' signature,
but I thought that this information does not help in the robustness of
an implementation. The role of jdiff is to minimize the time programmers
take in order to compare their implementation against the api and *NOT*
to totally replace the "comparing" proccess.
 
> Also, if the JDK declares a checked exception in the throws clause, we
> want to be compatible with that.  So this is a situation where we want
> to make sure to check the actual code, not the javadoc.

How the method behaves as a whole (even in exceptional situations) is
IMHO very important. That's why, provided that the programmer is aware
of "all" the normal and exceptional situations that emerge through a
call of his method by a client, a proper documentation *must* exist
above the method(or constructor) describing the functionality of the
implementation. So when your method's/constructor's declaration *and*
documentation, does not match the ones from sun, jdiff outputs the
differences. Is that clear?

> One approach would be to look at the throws clause but then omit all
> unchecked exceptions.  Also, the result should be sorted, so that
> ordering differences aren't considered.

Read above. The new version of jdiff, with the help of Michael Koch,
does the sorting and contains a lot of bugfixes.