[tor-bugs] #18955 [Metrics/CollecTor]: javadoc coverage

[Tor Bug Tracker & Wiki]

#18955: javadoc coverage
-------------------------------+------------------------
 Reporter:  iwakeh             |          Owner:  iwakeh
     Type:  task               |         Status:  new
 Priority:  Medium             |      Milestone:
Component:  Metrics/CollecTor  |        Version:
 Severity:  Normal             |     Resolution:
 Keywords:  ctip               |  Actual Points:
Parent ID:                     |         Points:
 Reviewer:                     |        Sponsor:
-------------------------------+------------------------

Comment (by iwakeh):

 In general, that sounds fine to me.

 It might be useful to separate the javadoc checks from all the other
 checkstyle checks, i.e. have another ant task `check-javadoc`.
 The current `metrics_checks.xml` could be split into
 `metrics_checks_javadoc.xml` (with just javdoc checks) and
 `metrics_checks.xml` with the other checks.
 This way there is no cluttering with the javadoc warnings, but the check
 is available. And, this kind of separation will be useful in future, too.

 >  ... rephrasing Javadoc that doesn't start with a summary sentence
 (happy to conform to that rule if it's in the guide) ...
 The summary sentence should start with a summary sentence/fragment, cf.
 [https://google.github.io/styleguide/javaguide.html#s7.2-summary-fragment
 Style Guide].

 Good news:
 We do not need to change the style guide for not writing javadoc for
 obvious (e.g. getter and setter) methods, cf.
 [https://google.github.io/styleguide/javaguide.html#s7.3.1-javadoc-
 exception-self-explanatory here].

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