Manu requested that we use this approach instead of adding
`@SuppressWarnings("unused")` at each affected catch block. That
seems reasonable to me, given the large number of such warnings and
the lack of likely harm from ignoring such caught exceptions.
Fixing these Javadoc comments would require adding packages to various
other packages' build paths. In some of the cases suppressed,
changing build paths in that manner would create circular build
dependencies. In other cases, it would simply add a Javadoc-motivated
dependency that does not exist for the real code, which seems
undesirable. For a few cases, the reference seems to be to types in
code we don't even have here, such as code from "android" or
"org.mozilla" packages.
These changes turn off Eclipse warnings for Javadoc comments with
missing tags, such as "@throw" or "@param".
We don't turn this warning off in all projects. Rather, we turn it
off only in projects that were producing at least one such warning.
In other words, if a project was already completely "clean" with
respect to this warning, then we leave this warning enabled for that
project.
Turning off these warnings is a partial declaration of Javadoc
bankruptcy. In an ideal world, we would enable and fix all of these
warnings. However, there are 327 of them. Apparently the WALA team's
implicit coding style says that omitting Javadoc tags is OK. If
there's no intent to systematically add these tags, then we may as
well turn off these warnings so that we can see other warnings that we
may want to fix.
These changes turn off Eclipse warnings for documentable items without
Javadoc comments. In some subprojects, we turn these off entirely.
In others, we leave these warnings on for public items but not for
items whose visibility is protected or below.
We don't turn this warning off in all projects. Rather, we turn it
off only in projects that were producing at least one such warning.
In other words, if a project was already completely "clean" with
respect to this warning, then we leave this warning enabled for that
project.
Turning off these warnings is a partial declaration of Javadoc
bankruptcy. In an ideal world, we would enable and fix all of these
warnings. However, there are 1,366 of them. Apparently the WALA
team's implicit coding style says that omitting Javadoc comments is
OK. If there's no intent to systematically add documentation, then we
may as well turn off these warnings so that we can see other warnings
that we may want to fix.
These arise, for example, when Javadoc documentation on a public class
includes a @link to a private field. I can see how this would be
problematic for closed-source Java code where private items are
invisible to outsiders. However, given that WALA is open source,
nothing is truly non-visible. If the WALA documentation authors
considered non-visible references useful when explaining things,
that's fine with me.
We don't turn this warning off in all projects. Rather, we turn it
off only in projects that were producing at least one such warning.
In other words, if a project was already completely "clean" with
respect to this warning, then we leave this warning enabled for that
project.
These changes turn off Eclipse warnings for Javadoc tags without
descriptions. In some subprojects, we turn these off entirely. In
others, leave on missing-descrption checks for "@return" tags only.
We don't turn this warning off in all projects. Rather, we turn it
off only in projects that were producing at least one such warning.
In other words, if a project was already completely "clean" with
respect to this warning, then we leave this warning enabled for that
project.
Turning off these warnings is a partial declaration of Javadoc
bankruptcy. In an ideal world, we would enable and fix all of these
warnings. However, there are 576 of them. Apparently the WALA team's
implicit coding style says that omitting descriptions is OK. If
there's no intent to systematically add descriptions, then we may as
well turn off these warnings so that we can see other warnings that we
may want to fix.
As it turns out, I should have been using "? extends InstanceKey" rather
than "? super InstanceKey". But really, we can just use "?" here since
HeapGraph itself constrains its own type parameter appropriately.
Eclipse warns that the "if" statements' true blocks are dead, and
indeed the conditions being tested here can never be true. It's a
little subtle why that's so, though. Changing them to "assert"
statements removes two warnings about deprecated code, while still
helping human readers understand what invariants must hold here.
The assert will throw AssertionError if it finds a bad argument,
unless the code is running without assertion checking enabled. The
"if" will throw an IllegalArgumentException if it finds the same bad
argument, and that check is always enabled. Better to be consistent
in what exception is used to report a bad argument. Since the "if" is
always active, let's go with that and remove the redundant,
not-always-active assert.
We used to use junit.framework.Assert for test assertions, and that
class reports failures by throwing
junit.framework.AssertionFailedError. However, junit.framework.Assert
is obsoleted by org.junit.Assert, and we've already replaced the
former with the latter. org.junit.Assert reports failures by throwing
java.lang.AssertionError, so that's what we need to expect in our
testing infrastructure.
All of these involve conditionals that check some static, final debug
flag or debug level. The code will indeed be dead if WALA is built
with those debug facilities turned off. But we still want the code
present in case someone needs to turn some aspect of debugging on for
a while.
The supposedly deprecated function (CGNode.addTarget) really seems to
be intended for internal use, not deprecated per se. We are an
internal user here, so presumably it's OK for us to be using this API
entry point.
Near as I can tell, the request for a deprecated version here is
intentional. The non-deprecated version (AST.JLS8) is the latest and
greatest, but as far as I can tell we really do want the older version
here.
This should make it easier for newcomers to get WALA up and running
from sources. One no longer needs to manually find "dx.jar" using
instructions given at
<http://wala.sourceforge.net/wiki/index.php/UserGuide:Getting_Started#Building_the_code>
or
<https://groups.google.com/forum/#!msg/wala-sourceforge-net/cBYsfEvYVG0/Ua52dyQQU-YJ>.
Those instructions were already out-of-date, anyway.
Given that an official release of "dx.jar" is available in Maven, it
would be nice to have Maven itself manage that dependency.
Unfortunately, it seems that WALA in general does not use Maven for
dependency management. As far as I can tell, the Maven configuration
just calls out to Ant for doing builds, including having Ant download
other needed components. If WALA ever moved to using Maven more
fully, downloading "dx.jar" could easily come along with that.
Manu Sridharan
Ben Liblit