• Type: Sub-task
    • Status: Resolved
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.0.0uimaFIT
    • Component/s: uimaFIT
    • Labels:


      Marshall 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).





            • Assignee:
              rec Richard Eckart de Castilho
              rec Richard Eckart de Castilho
            • Votes:
              0 Vote for this issue
              1 Start watching this issue


              • Created: