Set Claude to work analyzing all of the javadoc errors and warnings in the util package. Spoiler: it was a lot

Author: AngledLuffa

src/edu/stanford/nlp/util/AbstractIterator.java

@@ -5,9 +5,14 @@
 /**
  * Iterator with <code>remove()</code> defined to throw an
  * <code>UnsupportedOperationException</code>.
+ *
+ * @param <E> The type of the elements returned by this iterator
  */
 public abstract class AbstractIterator<E> implements Iterator<E> {
 
+  /** Constructor for subclasses. */
+  public AbstractIterator() { }
+
   /** {@inheritDoc} */
   @Override
   public abstract boolean hasNext();

src/edu/stanford/nlp/util/AcronymMatcher.java

@@ -208,18 +208,44 @@ private static List<String> getMainTokenStrs(String[] tokens) {
     return mainTokenStrs;
   }
 
+  /**
+   * Filters a list of tokens down to the "main" tokens: the nonempty ones
+   * which are at least 4 characters long or start with an uppercase letter.
+   *
+   * @param tokens The tokens to filter
+   * @return A new list containing the main tokens, in their original order
+   */
   public static List<String> getMainStrs(List<String> tokens) {
     List<String> mainTokenStrs = new ArrayList<>(tokens.size());
     mainTokenStrs.addAll(tokens.stream().filter(text -> !text.isEmpty() && (text.length() >= 4 || Character.isUpperCase(text.charAt(0)))).collect(Collectors.toList()));
     return mainTokenStrs;
   }
 
+  /**
+   * Returns true if the given string is an acronym of the given tokens.
+   *
+   * @param str The candidate acronym
+   * @param tokens The tokens of the candidate expansion
+   * @return true if {@code str} is an acronym of {@code tokens}
+   * @see AcronymMatcher#isAcronymImpl(String, List)
+   */
   public static boolean isAcronym(String str, String[] tokens) {
     return isAcronymImpl(str, Arrays.asList(tokens));
   }
 
   // Public static utility methods
 
+  /**
+   * Returns true if the given string is an acronym of the given tokens.
+   * The characters '-', '.' and '_' are first removed from {@code str}; if its length
+   * then differs from the number of tokens, stopwords are removed from the tokens.
+   * It is an acronym if each character matches (case-insensitively) the first
+   * character of the corresponding token. Empty tokens match any character.
+   *
+   * @param str The candidate acronym
+   * @param tokens The tokens of the candidate expansion
+   * @return true if {@code str} is an acronym of {@code tokens}
+   */
   public static boolean isAcronymImpl(String str, List<String> tokens) {
     // Remove some words from the candidate acronym
     str = discardPattern.matcher(str).replaceAll("");
@@ -242,6 +268,16 @@ public static boolean isAcronymImpl(String str, List<String> tokens) {
     }
   }
 
+  /**
+   * Returns true if the given string is an acronym of the given tokens.
+   * Tokens which are {@link CoreMap}s contribute their text annotation;
+   * any other object contributes its {@code toString()}.
+   *
+   * @param str The candidate acronym
+   * @param tokens The tokens of the candidate expansion
+   * @return true if {@code str} is an acronym of {@code tokens}
+   * @see AcronymMatcher#isAcronymImpl(String, List)
+   */
   public static boolean isAcronym(String str, List<?> tokens) {
     List<String> strs = new ArrayList<>(tokens.size());
     for (Object tok : tokens) {
@@ -259,6 +295,8 @@ public static boolean isAcronym(String str, List<?> tokens) {
   /**
    * Returns true if either chunk1 or chunk2 is acronym of the other.
    *
+   * @param chunk1 The first chunk, with text and tokens annotations
+   * @param chunk2 The second chunk, with text and tokens annotations
    * @return true if either chunk1 or chunk2 is acronym of the other
    */
   public static boolean isAcronym(CoreMap chunk1, CoreMap chunk2) {
@@ -276,7 +314,15 @@ public static boolean isAcronym(CoreMap chunk1, CoreMap chunk2) {
     return isAcro;
   }
 
-  /** @see AcronymMatcher#isAcronym(edu.stanford.nlp.util.CoreMap, edu.stanford.nlp.util.CoreMap) */
+  /**
+   * Returns true if either chunk1 or chunk2 is acronym of the other.
+   * The text of each chunk is its tokens joined with spaces.
+   *
+   * @param chunk1 The tokens of the first chunk
+   * @param chunk2 The tokens of the second chunk
+   * @return true if either chunk1 or chunk2 is acronym of the other
+   * @see AcronymMatcher#isAcronym(edu.stanford.nlp.util.CoreMap, edu.stanford.nlp.util.CoreMap)
+   */
   public static boolean isAcronym(String[] chunk1, String[] chunk2) {
     String text1 = StringUtils.join(chunk1);
     String text2 = StringUtils.join(chunk2);
@@ -292,6 +338,15 @@ public static boolean isAcronym(String[] chunk1, String[] chunk2) {
     return isAcro;
   }
 
+  /**
+   * Returns true if either chunk1 or chunk2 is a "fancy" acronym of the other,
+   * as determined by {@link #isFancyAcronymImpl(String, List)}.
+   * The text of each chunk is its tokens joined with spaces.
+   *
+   * @param chunk1 The tokens of the first chunk
+   * @param chunk2 The tokens of the second chunk
+   * @return true if either chunk is a fancy acronym of the other
+   */
   public static boolean isFancyAcronym(String[] chunk1, String[] chunk2) {
     String text1 = StringUtils.join(chunk1);
     String text2 = StringUtils.join(chunk2);
@@ -301,6 +356,14 @@ public static boolean isFancyAcronym(String[] chunk1, String[] chunk2) {
     return isFancyAcronymImpl(text1, tokenStrs2) || isFancyAcronymImpl(text2, tokenStrs1);
   }
 
+  /**
+   * Returns true if the characters of {@code str} (after removing '-', '.' and '_')
+   * occur in order, case-sensitively, in the space-joined text of the tokens.
+   *
+   * @param str The candidate acronym
+   * @param tokens The tokens of the candidate expansion
+   * @return true if {@code str} is a fancy acronym of {@code tokens}
+   */
   public static boolean isFancyAcronymImpl(String str, List<String> tokens) {
     str = discardPattern.matcher(str).replaceAll("");
     String text = StringUtils.join(tokens);

src/edu/stanford/nlp/util/ArgumentParser.java

@@ -68,16 +68,37 @@ public class ArgumentParser  {
 
   private ArgumentParser() {} // static class
 
+  /** Marks a field as an option which can be filled from properties or command-line arguments. */
   @Documented
   @Retention(RetentionPolicy.RUNTIME)
   @Target(ElementType.FIELD)
   public @interface Option {
+    /**
+     * The name of the option (matched case-insensitively).
+     *
+     * @return The option name; if empty, the field name is used
+     */
     String name() default "";
 
+    /**
+     * A description of the option, shown in usage messages.
+     *
+     * @return The description of the option
+     */
     String gloss() default "";
 
+    /**
+     * Whether the option must be set; if a required option is missing, filling options throws an exception.
+     *
+     * @return true if the option is required
+     */
     boolean required() default false;
 
+    /**
+     * Alternate names for the option.
+     *
+     * @return A comma-separated list of alternate names, or empty for none
+     */
     String alt() default "";
   }
 
@@ -89,10 +110,13 @@ private ArgumentParser() {} // static class
       ArgumentParser.class,
   };
 
+  /** The classes to fill options in; if null, all classes visible on the classpath are searched. */
   @Option(name = "option_classes", gloss = "Fill options from these classes")
   public static Class<?>[] optionClasses; // = null;
+  /** The number of threads to use; defaults to the number of available processors. */
   @Option(name = "threads", gloss = "Number of threads on machine")
   public static int threads = Runtime.getRuntime().availableProcessors();
+  /** The host name of this machine, or "(unknown)" if it could not be determined. */
   @Option(name = "host", gloss = "Name of computer we are running on")
   public static String host = "(unknown)";
   @SuppressWarnings({"FieldCanBeLocal", "RedundantFieldInitialization"})

src/edu/stanford/nlp/util/ArrayCoreMap.java

@@ -261,6 +261,12 @@ public void compact() {
     }
   }
 
+  /**
+   * Reallocates the internal arrays to hold exactly newSize entries.
+   *
+   * @param newSize The new capacity
+   * @throws RuntimeException if newSize is smaller than the current size
+   */
   public void setCapacity(int newSize) {
     if (size > newSize) { throw new RuntimeException("You cannot set capacity to smaller than the current size."); }
     Class[] newKeys = new Class[newSize];

src/edu/stanford/nlp/util/ArrayHeap.java

@@ -18,6 +18,7 @@
  * @author Dan Klein
  * @author Christopher Manning
  * @version 1.2, 07/31/02
+ * @param <E> the type of elements held in the heap
  */
 public class ArrayHeap<E> extends AbstractSet<E> implements Heap<E>  {
 
@@ -283,12 +284,21 @@ public void clear() {
     objectToEntry.clear();
   }
 
+  /**
+   * Logs each array position with the score of its entry, in array order.
+   * All elements must implement {@link Scored}, or a ClassCastException is thrown.
+   */
   public void dump() {
     for (int j = 0; j < indexToEntry.size(); j++) {
       log.info(" " + j + " " + ((Scored) indexToEntry.get(j).object).score());
     }
   }
 
+  /**
+   * Checks the heap ordering and the stored array positions, logging any problems.
+   * If the ordering is violated, the heap is dumped and the JVM is exited
+   * (with status 0).
+   */
   public void verify() {
     for (int i = 0; i < indexToEntry.size(); i++) {
       if (i != 0) {
@@ -316,12 +326,22 @@ public ArrayHeap(Comparator<? super E> cmp) {
     objectToEntry = Generics.newHashMap();
   }
 
+  /** Create an ArrayHeap with the given initial capacity.
+   *
+   *  @param cmp The objects added will be ordered using the {@code Comparator}.
+   *  @param initCapacity The initial capacity of the backing list and map
+   */
   public ArrayHeap(Comparator<? super E> cmp, int initCapacity) {
     this.cmp = cmp;
     indexToEntry = new ArrayList<>(initCapacity);
     objectToEntry = Generics.newHashMap(initCapacity);
   }
 
+  /**
+   * Returns the elements in a new LinkedList, in the heap's iteration (sorted) order.
+   *
+   * @return A new list of the heap's elements in sorted order
+   */
   public List<E> asList() {
     return new LinkedList<>(this);
   }

src/edu/stanford/nlp/util/ArrayMap.java

@@ -8,13 +8,19 @@
  *
  * @author Dan Klein
  * @author Roger Levy
+ *
+ * @param <K> The type of the keys
+ * @param <V> The type of the values
  */
 public final class ArrayMap<K,V> extends AbstractMap<K,V> implements Serializable {
 
   private static final long serialVersionUID = 1L;
 
+  /** The entries; only the first {@code size} slots are in use. */
   private Entry<K,V>[] entryArray;
+  /** The length of {@code entryArray}. */
   private int capacity;
+  /** The number of entries in the map. */
   private int size;
 
   static final class Entry<K,V> implements Map.Entry<K,V>, Serializable {
@@ -69,20 +75,31 @@ public String toString() {
   }
 
 
+  /** Creates an empty map with an initial capacity of 2. */
   @SuppressWarnings("unchecked")
   public ArrayMap() {
     size = 0;
     capacity = 2;
     entryArray = new Entry[2];
   }
 
+  /**
+   * Creates an empty map with the given initial capacity.
+   *
+   * @param capacity The initial length of the backing array
+   */
   @SuppressWarnings("unchecked")
   public ArrayMap(int capacity) {
     size = 0;
     this.capacity = capacity;
     entryArray = new Entry[capacity];
   }
 
+  /**
+   * Creates a map containing the entries of {@code m}.
+   *
+   * @param m The map whose entries are copied
+   */
   @SuppressWarnings("unchecked")
   public ArrayMap(Map<? extends K, ? extends V> m) {
 	  size = 0;
@@ -91,6 +108,14 @@ public ArrayMap(Map<? extends K, ? extends V> m) {
 	  this.putAll(m);
   }
 
+  /**
+   * Creates a map from parallel arrays of keys and values.
+   * The keys are not checked for duplicates.
+   *
+   * @param keys The keys
+   * @param values The values; {@code values[i]} is the value for {@code keys[i]}
+   * @throws IllegalArgumentException if the arrays have different lengths
+   */
   @SuppressWarnings("unchecked")
   public ArrayMap(K[] keys, V[] values) {
     if (keys.length!=values.length) throw new IllegalArgumentException("different number of keys and values.");
@@ -102,10 +127,25 @@ public ArrayMap(K[] keys, V[] values) {
     }
   }
 
+  /**
+   * Creates an empty map with the default initial capacity.
+   *
+   * @param <K> The type of the keys
+   * @param <V> The type of the values
+   * @return A new empty ArrayMap
+   */
   public static <K, V> ArrayMap<K, V> newArrayMap() {
     return new ArrayMap<>();
   }
 
+  /**
+   * Creates an empty map with the given initial capacity.
+   *
+   * @param <K> The type of the keys
+   * @param <V> The type of the values
+   * @param capacity The initial length of the backing array
+   * @return A new empty ArrayMap
+   */
   public static <K, V> ArrayMap<K, V> newArrayMap(int capacity) {
     return new ArrayMap<>(capacity);
   }
@@ -198,6 +238,10 @@ public V remove(Object key) {
     return null;
   }
 
+  /**
+   * Cached value of {@link #hashCode()}; 0 means not yet computed.
+   * It is not reset when the map is modified.
+   */
   protected int hashCodeCache; // = 0;
 
   @Override

src/edu/stanford/nlp/util/ArraySet.java

@@ -8,10 +8,13 @@
 
 /**
  * An array-backed set.
+ *
+ * @param <E> the type of elements in the set
  * @author Roger Levy (rog@stanford.edu)
  */
 public class ArraySet<E> extends AbstractSet<E> implements Serializable {
 
+  /** The list holding the elements of the set. */
   private final List<E> backer;
 
   /**
@@ -24,6 +27,7 @@ public ArraySet() {
   /**
    * Constructs an ArraySet, using the given list as the backing collection.
    * Note that this is not a copy constructor!
+   * @param source the list to use (not copied) as the backing collection
    */
   public ArraySet(List<E> source) {
     this.backer = source;