Closed GoogleCodeExporter closed 9 years ago
Hi!
What tool did you use to generate these warnings? Looks interesting.
Regarding the imports you mention, I think they are necessary, because they
import classes that are referred to in the Javadoc comments.
For example, in ImmutableSortedMap, the TreeMap import is there because we
reference {@link TreeMap#comparator()} in the Javadoc (at line 605:
http://code.google.com/p/guava-libraries/source/browse/trunk/src/com/google/comm
on/collect/ImmutableSortedMap.java?r=113#602 ).
We could remove these imports by using fully-qualified class names in the
Javadoc comments (e.g. {@link java.util.TreeMap#comparator()}), but it would be
far less readable IMO.
I have only checked a few of the imports you listed, so it's possible that some
of them are indeed unnecessary, and are not even used in Javadoc comments.
Original comment by nev...@gmail.com
on 4 Feb 2011 at 12:12
It's possible some are unneeded, but if it took you 30 seconds to investigate,
that would be 30 seconds of your life you'd never get back.
Original comment by kevinb@google.com
on 4 Feb 2011 at 1:42
It's just Eclipse with the default setting which shows you which import aren't
needed.
I just quickly copied the result from Eclipse, but its true that the explicit
reference is necessary for the JavaDoc.
(http://java.sun.com/j2se/javadoc/faq/#missinglinks explains why an import with
@link is needed.)
There is just 2 useless imports because there are coming from inside the Guava
library:
The import com.google.common.base.Service.State is never
used AbstractService.java /guava-src-r08/com/google/common/util/concurrent line
24 Java Problem
The import com.google.common.base.Objects is never
used Table.java /guava-src-r08/com/google/common/collect line 21 Java Problem
I would better just reported them to avoid confusion.
Original comment by ullenb...@gmail.com
on 4 Feb 2011 at 4:48
About javadoc readability:
One pattern I use a lot is to use the fully qualified link with a readable
alias, so instead of this:
{@link java.util.TreeMap#comparator()})
I'd use this:
{@link java.util.TreeMap#comparator() TreeMap.comparator()})
This gets rid of the import but still renders the output nicely as
"TreeMap.comparator()"
Original comment by SeanPFl...@googlemail.com
on 4 Feb 2011 at 11:45
The readable alias is a nice trick, and I sometimes use it for other use cases
(not to hide inline imports).
I prefer having the import statements at the top of the file, instead of having
them inline inside Javadoc comments: I rarely look at the import statements,
and I think it's better to make the Javadoc comments as short as possible. With
the alias trick, the Javadoc looks the same either way, but the source code
comment is cleaner / shorter without inline imports + alias:
{@link TreeMap#comparator()}
versus
{@link java.util.TreeMap#comparator() TreeMap.comparator()}
Original comment by nev...@gmail.com
on 4 Feb 2011 at 12:55
Personally I would prefer to see full-qualified types for the JavaDoc and not
import statements for mainly two reasons:
a) Using an import declaration for any external tool is IMHO not the right way
to go. This is a technical dependency which has nothing to do with the source
itself but just "makes javadoc works". And I don't care that much about fully
qualified types in JavaDoc but I care about unnecessary imports which clutters
my source.
b) import declarations show dependencies the source have (not the JavaDoc).
That means from the imports I can see on what other types my type rely on. The
"JavaDoc-import" blurs this and it is misguiding that is shows a dependency
which is actually doesn’t exit. Should a Swing-class like java.awt.EventQueue
be imported from some core thread-class "just" to link to the JavaDoc and show
a similar behaviour? Yes, no, depends?
At least a comment on the import-line would be great. Or wait until Java X
comes with Annotations on import declarations to document it like
@VisibleForTesting does ...
Original comment by ullenb...@gmail.com
on 4 Feb 2011 at 9:55
Re comment 3:
import com.google.common.base.Service.State is never used AbstractService.java
If I removed that, I would have to change
* Implementing classes should invoke this method once their service has
* started. It will cause the service to transition from {@link
* State#STARTING} to {@link State#RUNNING}.
to
* Implementing classes should invoke this method once their service has
* started. It will cause the service to transition from {@link
* com.google.common.base.Service.State#STARTING} to {@link
* com.google.common.base.Service.State#RUNNING}.
in fact, to preserve the output I might even have to do this
* Implementing classes should invoke this method once their service has
* started. It will cause the service to transition from {@link
* com.google.common.base.Service.State#STARTING Service.STARTING} to {@link
* com.google.common.base.Service.State#RUNNING Service.RUNNING}.
(but that I don't know.)
Is that worth it? To me, the ease of readability of javadoc in both source
form and generated form is more important than these other concerns.
BTW, I even commented the import specifically hoping to avoid this complaint:
import com.google.common.base.Service.State; // javadoc needs this
It would be nice if javadoc didn't need it, and could just tell that "State"
refers to the nested class of the supertype, but it does.
Your other issue:
The import com.google.common.base.Objects is never used Table.java
is indeed used in javadoc just like all this others.
I'm going to let this drop now because it's really not worth all this time and
thought.
Original comment by kevinb@google.com
on 4 Feb 2011 at 11:47
This issue has been migrated to GitHub.
It can be found at https://github.com/google/guava/issues/<id>
Original comment by cgdecker@google.com
on 1 Nov 2014 at 4:15
Original issue reported on code.google.com by
ullenb...@gmail.com
on 3 Feb 2011 at 10:29