[tor-bugs] #16873 [Metrics/metrics-lib]: add javadoc to metrics-lib

[Tor Bug Tracker & Wiki]

#16873: add javadoc to metrics-lib
---------------------------------+------------------------------
 Reporter:  iwakeh               |          Owner:  karsten
     Type:  enhancement          |         Status:  needs_review
 Priority:  Low                  |      Milestone:
Component:  Metrics/metrics-lib  |        Version:
 Severity:  Normal               |     Resolution:
 Keywords:                       |  Actual Points:
Parent ID:  #18746               |         Points:
 Reviewer:                       |        Sponsor:
---------------------------------+------------------------------

Comment (by iwakeh):

 Wow! That was very fast!

 I still would like to read a little more of the javadoc.

 When looking (w/o reading much yet) at the resulting HTML:
 * we could add the copyright notice as footer
 * the usage pages are often helpful when getting acquainted with a new api
 * window title and
 * overview page title are missing.

 For these we need some more attributes in the javadoc task:
 {{{
   <javadoc destdir="${docs}"
            footer="(C) 2016 The Tor Project, Inc."
            doctitle="metrics-lib API Documentation"
            use="true"
            windowtitle="metrics-lib API Documentation">
     <classpath refid="classpath"/>
     <fileset dir="${sources}">
       <exclude name="**/impl/**"/>
     </fileset>
   </javadoc>
 }}}

 It might be useful to introduce the `@since <version>` tags for all the
 documented methods?
 (as the java jdk does, there I really need it often when switching between
 java versions I only need to keep the latest doc around.)

 As said above; I'll get back to the javadoc content in another comment
 soon.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/16873#comment:18>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online