#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 _______________________________________________ tor-bugs mailing list tor-bugs@lists.torproject.org https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-bugs