Update documentation on TermAnnotation.

phenol-core/src/main/java/org/monarchinitiative/phenol/ontology/data/TermAnnotation.java

@@ -4,44 +4,35 @@
 import java.util.Optional;
 
 /**
- * A {@link TermAnnotation} links a {@link TermId} to a <code>String</code> <b>label</b> of a "world
- * object".
- *
- * <p>For all annotated "world objects", the labels have to be unique for each object. The
+ * A {@link TermAnnotation} links a {@link TermId} to {@link TermId} of a <em>"world object"</em>.
+ * <p>
+ * For all annotated "world objects", the labels have to be unique for each object. The
  * annotations can then be used for, e.g., feeding into the information content computation and thus
  * into the similarity metrics computation algorithms.
  *
- * <p>Implementing classes have to properly implement <code>hashValue()</code> and <code>equals()
- * </code>.
- *
  * @author <a href="mailto:[email protected]">Manuel Holtgrewe</a>
  * @author <a href="mailto:[email protected]">Sebastian Koehler</a>
  */
 public interface TermAnnotation extends Identified, Serializable, Comparable<TermAnnotation> {
    long serialVersionUID = 2L;
 
   /**
-   * Query for "world object" label.
-   *
-   * @return The "world object" label that the term is annotated with.
+   * Get term ID of the "world object".
+   * <p>
+   * Note, this is <em>NOT</em> the annotation ID which can be obtained by {@link #id()}.
    */
   TermId getItemId();
 
   /**
-   * Query for evidence code.
-   *
-   * <p>The default implementation returns an empty {@link Optional} value.
-   *
-   * @return Optional {@code String} with the identifier of the evidence code.
+   * Get an optional with an evidence code of the annotation.
    */
+  // TODO - should we really return EvidenceCode here?
   default Optional<String> getEvidenceCode() {
     return Optional.empty();
   }
 
   /**
-   * Query for frequency of annotation in percent.
-   *
-   * <p>The default implementation always returns {@code Optional.empty()}.
+   * Get an optional frequency of the annotation in <em>percent</em>.
    */
   default Optional<Float> getFrequency() {
     return Optional.empty();