[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 iwakeh):

 Replying to [comment:9 karsten]:
 > 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?)
 Interesting. Let's move this discussion to #18797.

 >
 > 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?
 Not at all crazy. I thought that the package javadoc for impl could simply
 state general information, like:
 * this is _the_ reference implementation of the descriptor api
 * design goals for the implementation
 * advantages as well as areas for improvement, if known
 * and that there is no other javadoc inside impl
 * and ...

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