[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:
-------------------------+-----------------------------------

Comment (by karsten):

 I tend to agree with you regarding `@return` comments.  Though even
 Google's Java Style guide requires that "at-clause" to "never appear with
 an empty description."  And I think we'd have to disable some warnings in
 Eclipse and Ant if we want to leave them out.  Not saying that we must
 include them, but this seems like an important decision to make.  I'm fine
 postponing it and including simple Javadoc comments in 2.0.0.

 Oh, and let me make this discussion slightly more difficult: I pondered
 adding a `DescriptorGenerator` a while ago, where one would construct a
 new instance of a `Descriptor`, call its setters to give it some values,
 and then have the generator generate a text representation of that
 descriptor.  This would be useful for testing and maybe other things.
 Now, would the Javadoc of these setters copy the Javadoc of the getters or
 simply link to them?  Or would we use some smarter pattern for building
 these instances?  (And is there a smarter pattern for parsed descriptors
 than a huge interface with dozens of getters?)

 Regarding package descriptions, having one for `org.torproject.descriptor`
 would be very valuable.  But my original plan was to exclude
 `org.torproject.odescriptor.impl` from Javadoc entirely.  Is that crazy?

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