[tor-commits] [onionoo/release] Adds JavaDoc for NodeStatus class

[karsten at torproject.org]

commit 02f3d0ce5661ee4552b1076b7c6b3bb0fef0353c
Author: Iain R. Learmonth <irl at fsfe.org>
Date:   Tue Aug 14 14:15:03 2018 +0100

    Adds JavaDoc for NodeStatus class
---
 .../org/torproject/onionoo/docs/NodeStatus.java    | 63 +++++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java
index b2b6c8e..c0c6adf 100644
--- a/src/main/java/org/torproject/onionoo/docs/NodeStatus.java
+++ b/src/main/java/org/torproject/onionoo/docs/NodeStatus.java
@@ -23,6 +23,58 @@ import java.util.TreeMap;
 import java.util.TreeSet;
 import java.util.stream.Collectors;
 
+/**
+ * NodeStatus documents contain persistent state for data about relays. These
+ * are read by the hourly updater and then updated with new details where there
+ * are relevant descriptors, consensuses or other documents available.
+ *
+ * <p>At the end of each run of the hourly updater, these documents are
+ * concatenated and written to a single file in <code>status/summary</code>.
+ * Each line contains a single document.
+ *
+ * <p>A new NodeStatus can be created from a string using the
+ * {@link #fromString(String)} static method. To create a serialization, the
+ * {@link #toString()} method can be used.
+ *
+ * <p>The lines are formed of tab-separated values. There must be at least
+ * 23 fields present in the document. Additional fields may be present but
+ * are not required for the document to be valid. A summary of the encoding
+ * can be found here:
+ *
+ * <ol start="0">
+ * <li>"r" or "b" to represent a relay or a bridge</li>
+ * <li>Nickname</li>
+ * <li>ASCII representation of hex-encoded fingerprint</li>
+ * <li>OR Addresses<li>
+ * <li>Last seen (date portion)</li>
+ * <li>Last seen (time portion)</li>
+ * <li>OR Port</li>
+ * <li>Dir Port</li>
+ * <li>Relay Flags</li>
+ * <li>Consensus Weight</li>
+ * <li>Country Code</li>
+ * <li>Blank field (previously used for host name)</li>
+ * <li>Last reverse DNS lookup time (milliseconds)</li>
+ * <li>Default policy</li>
+ * <li>Port list</li>
+ * <li>First seen (date portion)</li>
+ * <li>First seen (time portion)</li>
+ * <li>Last address change (date portion)</li>
+ * <li>Last address change (time portion)</li>
+ * <li>AS Number</li>
+ * <li>Contact</li>
+ * <li>Recommended version (boolean)</li>
+ * <li>Family</li>
+ * <li>Version</li>
+ * <li>Blank field (previously used for host name)</li>
+ * <li>Version status</li>
+ * <li>AS Name</li>
+ * <li>Verified and unverified host names</li>
+ * </ol>
+ *
+ * <p>This list only provides a summary, individual fields can have
+ * complex encodings with nested lists.
+ */
 public class NodeStatus extends Document {
 
   private static final Logger log = LoggerFactory.getLogger(
@@ -489,7 +541,14 @@ public class NodeStatus extends Document {
   }
 
   /** Instantiates a new node status object from the given string that may
-   * have been produced by {@link #toString()}. */
+   * have been produced by {@link #toString()}. A document that has been
+   * written by a previous version of Onionoo that did not include all the
+   * currently supported fields will still be accepted, but will contain
+   * the new fields if serialized again using {@link #toString()}. A
+   * document that has been generated by a newer version of Onionoo that
+   * contains new fields will be accepted, but those new fields will be
+   * ignored and the data discarded if serialized again using
+   * {@link #toString()}. */
   public static NodeStatus fromString(String documentString) {
     try {
       String[] parts = documentString.trim().split("\t");
@@ -648,6 +707,8 @@ public class NodeStatus extends Document {
     }
   }
 
+  /** Generates a String serialization of the node status object that could
+   * be used by {@link #fromString(String)} to recreate this object. */
   @Override
   public String toString() {
     StringBuilder sb = new StringBuilder();