Details
-
Sub-task
-
Status: Resolved
-
Minor
-
Resolution: Fixed
-
None
-
None
Description
schor says:
Here's some remarks on the Javadocs; I don't see this as a release issue though.
I see the conventional javadoc configuration was overridden by uimaFIT in that
it turned on the flag "linksource".
The convention in other UIMA projects has been to try to separate user-facing
Classes from internal implementation things, and have the Javadocs be only for
user things. To that end, the normal convention also has the javadocs exclude
"private" methods.
Turning on the linksource adds the sources to the Javadocs, and inserts links to
the sources from the corresponding javadoc classes and methods.
Although this is convenient, and may be desired, it has the disadvantages of
putting the source tree (at least the part that the Javadocs document) into the
javadoc html tree, as html files. This of course adds lots of files to the api
doc tree, and is a duplication of the source available via svn. (For instance,
the source can be obtained at an html link:
http://svn.apache.org/viewvc/uima/sandbox/uimafit/tags/uimafit-2.0.0-rc1/ etc.)
The other potential downside (which may be of no consequence in the case of
uimaFIT) is that adding the source, of course, exposes all the private internal
stuff. I agree this is only an issue if the goal of the Javadocs is to "filter"
the info into user-facing and internal details, and omit the internal details
(which may change more frequently than the user-facing stuff).
-Marshall