[tor-bugs] #16873 [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_information
 Priority:  Low          |      Milestone:
Component:  metrics-lib  |        Version:
 Severity:  Normal       |     Resolution:
 Keywords:               |  Actual Points:
Parent ID:  #18746       |         Points:
 Reviewer:               |        Sponsor:
-------------------------+-----------------------------------
Changes (by karsten):

 * status:  needs_review => needs_information


Comment:

 There, I pushed my earlier patch to
 [https://gitweb.torproject.org/user/karsten/metrics-lib.git/log/?h=javadoc
 my javadoc branch] and incorporated your feedback (thanks for that!).

 However, I think we'll have to include things like `@return` in the
 comments, and that leads to a whole lot of duplicate text with our
 interfaces full of getters.  And there are probably other conventions that
 we're violating in the current comments.

 Do you happen to know some good guidelines for writing javadoc comments,
 ideally one that is commonly used by other Java projects as well?  I would
 say let's take
 [http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
 what Oracle has on their website], but maybe there are better guidelines.

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