[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             |   Keywords:  ctip
Actual Points:                     |  Parent ID:
       Points:                     |   Reviewer:
      Sponsor:                     |
-----------------------------------+--------------------
 == How much javadoc is necessary for CollecTor?
 Currently, there are many checkstyle warnings about missing javadoc.
 To what extend should javadoc be added or the rules weakened?

 === Some Examples
 Many public methods are not accompanied by javadoc, for example:

 {{{
 #!java
   public BridgeDescriptorParser(SanitizedBridgesWriter sbw)
   public void parse(byte[] allData, String dateTime)
   public ArchiveWriter(Configuration config)
   public static void main(String[] args)
   public void storeVote(byte[] data, long validAfter,
       String fingerprint, String digest,
       SortedSet<String> serverDescriptorDigests)
 }}}



 -----
 Some simple comments could be turned into javadoc
 {{{
 #!java
   /* Delete all files from the rsync directory that have not been modified
    * in the last three days. */
   public void cleanUpRsyncDirectory()
 }}}
 ----

 The following should not be a warning:
 {{{
 #!java
   /**
    * Should we try to download the current microdesc consensus if we don't
    * have it?
    */
   private boolean downloadCurrentMicrodescConsensus;
 }}}
 leads to the checkstyle warning
 `First sentence of Javadoc is incomplete (period is missing) or not
 present. [SummaryJavadoc]`

 == General Questions
 Only document `public`?
 Let getters/setters go without javadoc?
 Try to use readable code instead of additional javadoc?
 ...

 Thoughts?

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