Improve javadoc for ExtraInfoDescriptor classes.

Remove javadoc warnings at build time and improve
overall code documentation.

src/main/java/org/torproject/descriptor/impl/ExtraInfoDescriptorImpl.java

@@ -3,9 +3,7 @@
 
 package org.torproject.descriptor.impl;
 
-import org.torproject.descriptor.BandwidthHistory;
-import org.torproject.descriptor.DescriptorParseException;
-import org.torproject.descriptor.ExtraInfoDescriptor;
+import org.torproject.descriptor.*;
 
 import java.io.File;
 import java.util.ArrayList;
@@ -20,14 +18,47 @@ import java.util.Set;
 import java.util.SortedMap;
 import java.util.TreeMap;
 
+/**
+ * Contains logic to work with extra-info descriptor files.
+ *
+ * The extra-info document format is defined in the dir-spec
+ * document.
+ *
+ * @see <a href="https://github.com/torproject/torspec/blob/main/dir-spec.txt#L893">dir-spec.txt</a>
+ *
+ * Descriptor keys are defined and their occurency is checked to
+ * make sure the descriptor file format is valid.
+ *
+ * Descriptor lines are parsed and their values can be accessed through the
+ * defined methods.
+ *
+ * When metrics library learns how to parse a new line for extra-info
+ * descriptor files all its fields, from the dir-spec document, are parsed in
+ * this class.
+ *
+ * The new key is added to {@link Key} and its occurence is checked in
+ * {@link ExtraInfoDescriptorImpl} constructor.
+ *
+ * @since 1.0.0
+ */
+
+
 public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
     implements ExtraInfoDescriptor {
 
   private static final long serialVersionUID = -4720810362228341775L;
 
+  /**
+   * Define keys that MUST occur exactly one time in every
+   * instance of the document type.
+   */
   private Set<Key> exactlyOnceKeys = EnumSet.of(
       Key.EXTRA_INFO, Key.PUBLISHED);
 
+  /**
+   * Define keys that MAY occur zero or one times in any instance of the
+   * document type, but MUST NOT occur more than once.
+   */
   private static final Set<Key> atMostOnceKeys = EnumSet.of(
       Key.IDENTITY_ED25519, Key.MASTER_KEY_ED25519, Key.READ_HISTORY,
       Key.WRITE_HISTORY, Key.DIRREQ_READ_HISTORY, Key.DIRREQ_WRITE_HISTORY,
@@ -41,6 +72,11 @@ public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
     super(descriptorBytes, offsetAndLimit, descriptorFile, false);
     this.parseDescriptorBytes();
     this.checkExactlyOnceKeys(exactlyOnceKeys);
+
+    /**
+     * When a key is added to {@link Key} it needs to be added here too.
+     * Either directly or to the methods that check the occurrence of the key.
+     */
     Set<Key> dirreqStatsKeys = EnumSet.of(
         Key.DIRREQ_STATS_END, Key.DIRREQ_V2_IPS, Key.DIRREQ_V3_IPS,
         Key.DIRREQ_V2_REQS, Key.DIRREQ_V3_REQS, Key.DIRREQ_V2_SHARE,
@@ -74,6 +110,13 @@ public abstract class ExtraInfoDescriptorImpl extends DescriptorImpl
     this.clearParsedKeys();
   }
 
+  /**
+   * Parse the descriptor file.
+   *
+   * @throws DescriptorParseException if any of the desriptor lines
+   * is not valid.
+   *
+   */
   private void parseDescriptorBytes() throws DescriptorParseException {
     Scanner scanner = this.newScanner().useDelimiter(NL);
     Key nextCrypto = Key.EMPTY;

src/main/java/org/torproject/descriptor/impl/Key.java

@@ -3,6 +3,17 @@ package org.torproject.descriptor.impl;
 import java.util.HashMap;
 import java.util.Map;
 
+/**
+ * Define keys from descriptor document files
+ *
+ * The extra-info document format is defined in the dir-spec
+ * document.
+ *
+ * @see <a href="https://github.com/torproject/torspec/blob/main/dir-spec.txt#L893">dir-spec.txt</a>
+ *
+ * Occurence of each key is checked in the respective implementation class.
+ */
+
 public enum Key {
 
   EMPTY("the-empty-key"),