Re: jdiff.sh (BETA)
Tom Tromey <[EMAIL PROTECTED]> writes: > > "Giannis" == Giannis Georgalis <[EMAIL PROTECTED]> 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. ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: jdiff.sh (BETA)
> "Giannis" == Giannis Georgalis <[EMAIL PROTECTED]> 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. 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. 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. Tom ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: jdiff.sh (BETA)
Eric Blake <[EMAIL PROTECTED]> writes:>
> Unchecked exceptions do not need to be reported. There are several
> places where Classpath purposefully omits mentioning unchecked
> exceptions in the throws clause, because it is just a waste of .class
> file size.
>
> For example, these two declarations are equivalent, but the second
> compiles to less space:
> void m() throws RuntimeException {}
> void m() {}
Yes, however jdiff.sh completely ignores the throws clause and instead
parses the javadoc comments above the class definition. That way we
will make sure that the programmer is aware (and has implemented
correctly) the potential exceptional situations of his code. So:
/*
* @throws RuntimeException (or @exception RuntimeException)
*/
public void m(){}
will be correct if and only if RuntimeException is documented in the
public void m()'s detailed description in the Sun's documentation.
Is that clear (and desirable)?
> Yes, it may be bad style, and even worse style is "int m()[]" instead
> of "int[] m()", but you should still check it, because it will help us
> clean up our bad style.
ok, I fully agree with you.
> Likewise, your code should not worry about the "synchronized" keyword,
> on classes or on methods, because different implementations can
> successfully synchronize without marking everything in the same manner.
ok, the new version successfully ignores the "synchronized" keyword.
--
Is God willing to prevent evil, but not able? Then he is not omnipotent.
Is he able, but not willing? Then he is malevolent.
Is he both able and willing? Then whence cometh evil?
Is he neither able nor willing? Then why call him God?
(Epicurus)
___
Classpath mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/classpath
Re: jdiff.sh (BETA)
Giannis Georgalis wrote:
> Hello again,
>
> After some useful comments and a bug report by Michael Koch, jdiff.sh
> 0.0.1 (BETA) now works in the following ways:
>
> * Handles interfaces correctly ... Give me some help here; When you
> have a public interface do all the methods-fields default to "public"?
> I always explicitly declare them "public", but that's not the case in
> eg. java.net.SocketOptions (is that a valid declaration?)
> (Thanks Michael)
Yes, ALL interface members (fields and abstract methods) are public,
whether the user marked them that way or not, and whether the interface
is public or not.
>
> * Extracts the exceptions (from the source code of eg. GNU classpath)
> from javadoc comments and _not_ from the methods (or constructors)
> signature. Doing the same for the api documentation, makes it
> report (correctly?) both checked and unchecked exceptions.
Unchecked exceptions do not need to be reported. There are several
places where Classpath purposefully omits mentioning unchecked
exceptions in the throws clause, because it is just a waste of .class
file size.
For example, these two declarations are equivalent, but the second
compiles to less space:
void m() throws RuntimeException {}
void m() {}
>
> * It still doesn't handle declarations (in .java source) of the type
> "type ID[]", and I did it on purpose because I think declaring it like
> this is a bad style as ID is *not* an array of type "type" (like C/C++
> arrays,for example), but a *reference* to an array object of type "type".
> But If you are *not* in any way willing to declare them as "type[] ID",
> I will fix it ...
Yes, it may be bad style, and even worse style is "int m()[]" instead of
"int[] m()", but you should still check it, because it will help us
clean up our bad style.
>
> * It ignores the "native" keyword from the source code.
Good point - whether a method is implemented in Java or natively does
not affect whether the method exists.
Likewise, your code should not worry about the "synchronized" keyword,
on classes or on methods, because different implementations can
successfully synchronize without marking everything in the same manner.
--
This signature intentionally left boring.
Eric Blake [EMAIL PROTECTED]
BYU student, free software programmer
___
Classpath mailing list
[EMAIL PROTECTED]
http://mail.gnu.org/mailman/listinfo/classpath
Re: jdiff.sh (BETA)
Michael Koch <[EMAIL PROTECTED]> writes: > I found this on the net: > > "Member declarations in an interface disallow the use of some > declaration modifiers; you cannot use transient, volatile, or > synchronized in a member declaration in an interface. Also, you may > not use the private and protected specifiers when declaring members > of an interface." > > http://java.sun.com/docs/books/tutorial/java/interpack/createinterface.html > > I think this implicitely means they are public. Ofcourse, but java is a pedantic language... I haven't used the official SDK from Sun for a long time, but as far as I remember you should explicitely declare them "public" or the byte compiler started to curse on you :). Additionaly, java was never fond of the term impicitely and consider that ommiting the visibility modifier, means that methods/fields have *package* scope. -- Is God willing to prevent evil, but not able? Then he is not omnipotent. Is he able, but not willing? Then he is malevolent. Is he both able and willing? Then whence cometh evil? Is he neither able nor willing? Then why call him God? (Epicurus) ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
Re: jdiff.sh (BETA)
> * Handles interfaces correctly ... Give me some help here; When > you have a public interface do all the methods-fields default to > "public"? I always explicitly declare them "public", but that's not > the case in eg. java.net.SocketOptions (is that a valid > declaration?) (Thanks Michael) I found this on the net: "Member declarations in an interface disallow the use of some declaration modifiers; you cannot use transient, volatile, or synchronized in a member declaration in an interface. Also, you may not use the private and protected specifiers when declaring members of an interface." http://java.sun.com/docs/books/tutorial/java/interpack/createinterface.html I think this implicitely means they are public. Michael -- Homepage: http://www.worldforge.org/ GPG-key: http://konqueror.dyndns.org/~mkoch/michael.gpg ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
jdiff.sh (BETA)
Hello again, After some useful comments and a bug report by Michael Koch, jdiff.sh 0.0.1 (BETA) now works in the following ways: * Handles interfaces correctly ... Give me some help here; When you have a public interface do all the methods-fields default to "public"? I always explicitly declare them "public", but that's not the case in eg. java.net.SocketOptions (is that a valid declaration?) (Thanks Michael) * Extracts the exceptions (from the source code of eg. GNU classpath) from javadoc comments and _not_ from the methods (or constructors) signature. Doing the same for the api documentation, makes it report (correctly?) both checked and unchecked exceptions. * It still doesn't handle declarations (in .java source) of the type "type ID[]", and I did it on purpose because I think declaring it like this is a bad style as ID is *not* an array of type "type" (like C/C++ arrays,for example), but a *reference* to an array object of type "type". But If you are *not* in any way willing to declare them as "type[] ID", I will fix it ... * It ignores the "native" keyword from the source code. * It features even *more* unimaginative variable names :) TODO: if you have a method that declares eg: @throws NullPointerException and @throws IOException. Is not handled correctly if on the manual they appear in a different order, eg. throws: IOException blah, blah NullPointerException blah, blah. I think I'll fix that some time today... and I'll change the version to 0.0.1 (that is without any greek letter in parentheses :)) Note, that Japitools is more professional and it does the same job. Give it a try, it has more features than jdiff.sh (which was made to relieve myself from the tedious work of looking up in the api every single method, not knowing the existance of Japitools.). I will contribute to Japitools jdiff.sh's html filter. However I am willing to continue to fix bugs and add futures to jdiff.sh if you ask me to, as it is neither difficult nor time consuming for me to do so... Thanks. PS. You can always find the newest version at http://majestix.ucnet.uoc.gr/~jgeorgal/pub/jdiff.sh -- Is God willing to prevent evil, but not able? Then he is not omnipotent. Is he able, but not willing? Then he is malevolent. Is he both able and willing? Then whence cometh evil? Is he neither able nor willing? Then why call him God? (Epicurus) ___ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
