[tor-commits] [collector/master] Write Javadocs to appease checkstyle.

[karsten at torproject.org]

commit 74bae5b448fd8684fcbfe06a409df459d1f539d3
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date:   Thu Jul 14 14:04:20 2016 +0200

    Write Javadocs to appease checkstyle.
---
 .../bridgedescs/BridgeDescriptorParser.java        |  6 +++--
 .../bridgedescs/SanitizedBridgesWriter.java        |  3 ++-
 .../collector/exitlists/ExitListDownloader.java    |  2 +-
 .../collector/index/CreateIndexJson.java           |  3 ++-
 .../org/torproject/collector/main/LockFile.java    |  6 +++--
 .../collector/relaydescs/ArchiveReader.java        |  9 ++++++--
 .../collector/relaydescs/ArchiveWriter.java        | 26 +++++++++++++---------
 .../relaydescs/CachedRelayDescriptorReader.java    |  3 ++-
 .../collector/relaydescs/ReferenceChecker.java     |  5 +++--
 .../relaydescs/RelayDescriptorParser.java          |  9 ++++++--
 .../collector/torperf/TorperfDownloader.java       |  2 +-
 11 files changed, 49 insertions(+), 25 deletions(-)

diff --git a/src/main/java/org/torproject/collector/bridgedescs/BridgeDescriptorParser.java b/src/main/java/org/torproject/collector/bridgedescs/BridgeDescriptorParser.java
index 337c2a3..6dc05b6 100644
--- a/src/main/java/org/torproject/collector/bridgedescs/BridgeDescriptorParser.java
+++ b/src/main/java/org/torproject/collector/bridgedescs/BridgeDescriptorParser.java
@@ -16,14 +16,16 @@ public class BridgeDescriptorParser {
 
   private Logger logger;
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Initializes a new bridge descriptor parser and links it to a
+   * sanitized bridges writer to sanitize and store bridge descriptors. */
   public BridgeDescriptorParser(SanitizedBridgesWriter sbw) {
     this.sbw = sbw;
     this.logger =
         LoggerFactory.getLogger(BridgeDescriptorParser.class);
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Parses the first line of the given descriptor data to determine the
+   * descriptor type and passes it to the sanitized bridges writer. */
   public void parse(byte[] allData, String dateTime) {
     try {
       BufferedReader br = new BufferedReader(new StringReader(
diff --git a/src/main/java/org/torproject/collector/bridgedescs/SanitizedBridgesWriter.java b/src/main/java/org/torproject/collector/bridgedescs/SanitizedBridgesWriter.java
index 1f48fb7..b1b9589 100644
--- a/src/main/java/org/torproject/collector/bridgedescs/SanitizedBridgesWriter.java
+++ b/src/main/java/org/torproject/collector/bridgedescs/SanitizedBridgesWriter.java
@@ -54,7 +54,8 @@ public class SanitizedBridgesWriter extends Thread {
 
   private static Logger logger = LoggerFactory.getLogger(SanitizedBridgesWriter.class);
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Executes the bridge-descriptors module using the given
+   * configuration. */
   public static void main(Configuration config) throws ConfigurationException {
 
     logger.info("Starting bridge-descriptors module of CollecTor.");
diff --git a/src/main/java/org/torproject/collector/exitlists/ExitListDownloader.java b/src/main/java/org/torproject/collector/exitlists/ExitListDownloader.java
index f54a427..5e17971 100644
--- a/src/main/java/org/torproject/collector/exitlists/ExitListDownloader.java
+++ b/src/main/java/org/torproject/collector/exitlists/ExitListDownloader.java
@@ -36,7 +36,7 @@ public class ExitListDownloader extends Thread {
 
   private static Logger logger = LoggerFactory.getLogger(ExitListDownloader.class);
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Execute the exit-lists module using the given configuration. */
   public static void main(Configuration config) throws ConfigurationException {
     logger.info("Starting exit-lists module of CollecTor.");
 
diff --git a/src/main/java/org/torproject/collector/index/CreateIndexJson.java b/src/main/java/org/torproject/collector/index/CreateIndexJson.java
index 70886bc..a39ef67 100644
--- a/src/main/java/org/torproject/collector/index/CreateIndexJson.java
+++ b/src/main/java/org/torproject/collector/index/CreateIndexJson.java
@@ -52,7 +52,8 @@ public class CreateIndexJson {
 
   static final TimeZone dateTimezone = TimeZone.getTimeZone("UTC");
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Creates indexes of directories containing archived and recent
+   * descriptors and write index files to disk. */
   public static void main(Configuration config)
       throws ConfigurationException, IOException {
     indexJsonFile =  new File(config.getPath(Key.IndexPath).toFile(), "index.json");
diff --git a/src/main/java/org/torproject/collector/main/LockFile.java b/src/main/java/org/torproject/collector/main/LockFile.java
index 83cb603..977b0b9 100644
--- a/src/main/java/org/torproject/collector/main/LockFile.java
+++ b/src/main/java/org/torproject/collector/main/LockFile.java
@@ -28,7 +28,9 @@ public class LockFile {
     this.moduleName = moduleName;
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Acquires the lock by checking whether a lock file already exists,
+   * and if not, by creating one with the current system time as
+   * content. */
   public boolean acquireLock() {
     this.logger.debug("Trying to acquire lock...");
     try {
@@ -54,7 +56,7 @@ public class LockFile {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Releases the lock by deleting the lock file, if present. */
   public void releaseLock() {
     this.logger.debug("Releasing lock...");
     this.lockFile.delete();
diff --git a/src/main/java/org/torproject/collector/relaydescs/ArchiveReader.java b/src/main/java/org/torproject/collector/relaydescs/ArchiveReader.java
index 8d82f5c..25f5859 100644
--- a/src/main/java/org/torproject/collector/relaydescs/ArchiveReader.java
+++ b/src/main/java/org/torproject/collector/relaydescs/ArchiveReader.java
@@ -43,7 +43,9 @@ public class ArchiveReader {
   private Map<String, Set<String>> microdescriptorValidAfterTimes =
       new HashMap<String, Set<String>>();
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Reads all descriptors from the given directory, possibly using a
+   * parse history file, and passes them to the given descriptor
+   * parser. */
   public ArchiveReader(RelayDescriptorParser rdp, File archivesDirectory,
       File statsDirectory, boolean keepImportHistory) {
 
@@ -272,7 +274,10 @@ public class ArchiveReader {
         + ignoredFiles + " files.");
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores the valid-after time and microdescriptor digests of a given
+   * microdesc consensus, so that microdescriptors (which don't contain a
+   * publication time) can later be sorted into the correct month
+   * folders. */
   public void haveParsedMicrodescConsensus(String validAfterTime,
       SortedSet<String> microdescriptorDigests) {
     for (String microdescriptor : microdescriptorDigests) {
diff --git a/src/main/java/org/torproject/collector/relaydescs/ArchiveWriter.java b/src/main/java/org/torproject/collector/relaydescs/ArchiveWriter.java
index 3c3272c..3715a9f 100644
--- a/src/main/java/org/torproject/collector/relaydescs/ArchiveWriter.java
+++ b/src/main/java/org/torproject/collector/relaydescs/ArchiveWriter.java
@@ -108,7 +108,8 @@ public class ArchiveWriter extends Thread {
   private static final String MICRODESC = "microdesc";
   private static final String MICRODESCS = "microdescs";
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Executes the relay-descriptors module using the given
+   * configuration. */
   public static void main(Configuration config) throws ConfigurationException {
 
     logger.info("Starting relay-descriptors module of CollecTor.");
@@ -134,7 +135,7 @@ public class ArchiveWriter extends Thread {
     logger.info("Terminating relay-descriptors module of CollecTor.");
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Initialize an archive writer with a given configuration. */
   public ArchiveWriter(Configuration config) throws ConfigurationException {
     this.config = config;
     storedServerDescriptorsFile =
@@ -319,7 +320,8 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Compiles a message with statistics on stored descriptors by type for
+   * later inclusion in the log and resets counters. */
   public void intermediateStats(String event) {
     intermediateStats.append("While " + event + ", we stored "
         + this.storedConsensusesCounter + " consensus(es), "
@@ -649,7 +651,8 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores a consensus to disk and adds all referenced votes and server
+   * descriptors to the list of missing descriptors. */
   public void storeConsensus(byte[] data, long validAfter,
       SortedSet<String> dirSources,
       SortedSet<String> serverDescriptorDigests) {
@@ -672,7 +675,8 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores a microdesc consensus to disk and adds all referenced
+   * microdescriptors to the list of missing descriptors. */
   public void storeMicrodescConsensus(byte[] data, long validAfter,
       SortedSet<String> microdescriptorDigests) {
     SimpleDateFormat yearMonthDirectoryFormat = new SimpleDateFormat(
@@ -699,7 +703,8 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores a vote to disk and adds all referenced server descriptors to
+   * the list of missing descriptors. */
   public void storeVote(byte[] data, long validAfter,
       String fingerprint, String digest,
       SortedSet<String> serverDescriptorDigests) {
@@ -727,7 +732,7 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores a key certificate to disk. */
   public void storeCertificate(byte[] data, String fingerprint,
       long published) {
     SimpleDateFormat printFormat = new SimpleDateFormat(
@@ -741,7 +746,8 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores a server descriptor to disk and adds the referenced
+   * extra-info descriptor to the list of missing descriptors. */
   public void storeServerDescriptor(byte[] data, String digest,
       long published, String extraInfoDigest) {
     SimpleDateFormat printFormat = new SimpleDateFormat("yyyy/MM/");
@@ -770,7 +776,7 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores an extra-info descriptor to disk. */
   public void storeExtraInfoDescriptor(byte[] data,
       String extraInfoDigest, long published) {
     SimpleDateFormat descriptorFormat = new SimpleDateFormat("yyyy/MM/");
@@ -798,7 +804,7 @@ public class ArchiveWriter extends Thread {
     }
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Stores a microdescriptor to disk. */
   public void storeMicrodescriptor(byte[] data,
       String microdescriptorDigest, long validAfter) {
     /* TODO We could check here whether we already stored the
diff --git a/src/main/java/org/torproject/collector/relaydescs/CachedRelayDescriptorReader.java b/src/main/java/org/torproject/collector/relaydescs/CachedRelayDescriptorReader.java
index f947895..6c18cdb 100644
--- a/src/main/java/org/torproject/collector/relaydescs/CachedRelayDescriptorReader.java
+++ b/src/main/java/org/torproject/collector/relaydescs/CachedRelayDescriptorReader.java
@@ -36,7 +36,8 @@ import java.util.TreeSet;
  */
 public class CachedRelayDescriptorReader {
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Reads cached-descriptor files from one or more directories and
+   * passes them to the given descriptor parser. */
   public CachedRelayDescriptorReader(RelayDescriptorParser rdp,
       String[] inputDirectories, File statsDirectory) {
 
diff --git a/src/main/java/org/torproject/collector/relaydescs/ReferenceChecker.java b/src/main/java/org/torproject/collector/relaydescs/ReferenceChecker.java
index efbcbe0..a749ff5 100644
--- a/src/main/java/org/torproject/collector/relaydescs/ReferenceChecker.java
+++ b/src/main/java/org/torproject/collector/relaydescs/ReferenceChecker.java
@@ -68,7 +68,7 @@ public class ReferenceChecker {
 
   private static final long THIRTY_DAYS = 30L * ONE_DAY;
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Initializes a reference checker using the given file paths. */
   public ReferenceChecker(File descriptorsDir, File referencesFile,
       File historyFile) {
     this.descriptorsDir = descriptorsDir;
@@ -76,7 +76,8 @@ public class ReferenceChecker {
     this.historyFile = historyFile;
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Checks references between descriptors, and if too many referenced
+   * descriptors are missing, puts out a warning to the logs. */
   public void check() {
     this.getCurrentTimeMillis();
     this.readReferencesFile();
diff --git a/src/main/java/org/torproject/collector/relaydescs/RelayDescriptorParser.java b/src/main/java/org/torproject/collector/relaydescs/RelayDescriptorParser.java
index 027237e..946a494 100644
--- a/src/main/java/org/torproject/collector/relaydescs/RelayDescriptorParser.java
+++ b/src/main/java/org/torproject/collector/relaydescs/RelayDescriptorParser.java
@@ -70,7 +70,10 @@ public class RelayDescriptorParser {
     this.ar = ar;
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Parses the given bytes to find out the contained descriptor type,
+   * forwards them to the archive writer to store them to disk, and tells
+   * the relay descriptor downloader and archive reader about the
+   * contained descriptor and all referenced descriptors. */
   public boolean parse(byte[] data) {
     boolean stored = false;
     try {
@@ -326,7 +329,9 @@ public class RelayDescriptorParser {
     return stored;
   }
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Forwards the given microdescriptor to the archive writer to store
+   * it to disk and tells the relay descriptor downloader that this
+   * microdescriptor is not missing anymore. */
   public void storeMicrodescriptor(byte[] data, String digest256Hex,
       String digest256Base64, long validAfter) {
     if (this.aw != null) {
diff --git a/src/main/java/org/torproject/collector/torperf/TorperfDownloader.java b/src/main/java/org/torproject/collector/torperf/TorperfDownloader.java
index 02d17ed..25164c9 100644
--- a/src/main/java/org/torproject/collector/torperf/TorperfDownloader.java
+++ b/src/main/java/org/torproject/collector/torperf/TorperfDownloader.java
@@ -36,7 +36,7 @@ import java.util.TreeMap;
 public class TorperfDownloader extends Thread {
   private static Logger logger = LoggerFactory.getLogger(TorperfDownloader.class);
 
-  @SuppressWarnings("checkstyle:javadocmethod")
+  /** Executes the torperf module using the given configuration. */
   public static void main(Configuration config) throws ConfigurationException {
     logger.info("Starting torperf module of CollecTor.");