(opennlp) 03/07: OPENNLP-1887: Tighten expander javadoc and document private helpers

[kr...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

krickert pushed a commit to branch wordnet-expansion
in repository https://gitbox.apache.org/repos/asf/opennlp.git

commit a1bbef72ffddf28b0adb15fcd231f53e8812962e
Author: Kristian Rickert <kr...@gmail.com>
AuthorDate: Sun Jul 12 20:41:20 2026 -0400

    OPENNLP-1887: Tighten expander javadoc and document private helpers
    
    Applies the review conventions from the OPENNLP-1869 review to the expansion layer: the default-choice essay shrinks to its contract sentence and the private helpers are documented.
---
 .../src/main/java/opennlp/wordnet/LexicalExpander.java            | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/opennlp-extensions/opennlp-wordnet/src/main/java/opennlp/wordnet/LexicalExpander.java b/opennlp-extensions/opennlp-wordnet/src/main/java/opennlp/wordnet/LexicalExpander.java
index d2eb019b6..75a9ca42d 100644
--- a/opennlp-extensions/opennlp-wordnet/src/main/java/opennlp/wordnet/LexicalExpander.java
+++ b/opennlp-extensions/opennlp-wordnet/src/main/java/opennlp/wordnet/LexicalExpander.java
@@ -143,6 +143,7 @@ public final class LexicalExpander {
     return collect(term, List.of(WordNetPOS.values()));
   }
 
+  /** Expands the term across the given parts of speech and returns the ranked, capped result. */
   private List<Expansion> collect(String term, List<WordNetPOS> poses) {
     if (term == null || term.isBlank()) {
       throw new IllegalArgumentException("The term must not be null or blank.");
@@ -196,6 +197,7 @@ public final class LexicalExpander {
     return lemma;
   }
 
+  /** Offers the synonyms, hypernym ancestors, and optional hyponyms of one sense into {@code best}. */
   private void expandSense(Synset sense, int rank, double senseWeight,
                            Map<String, Expansion> best, Set<String> excluded) {
     for (final String lemma : sense.lemmas()) {
@@ -244,6 +246,7 @@ public final class LexicalExpander {
     }
   }
 
+  /** Returns the synset ids of both the direct and the instance hypernyms of the synset. */
   private static List<String> hypernymsOf(Synset synset) {
     final List<String> direct = synset.related(WordNetRelation.HYPERNYM);
     final List<String> instance = synset.related(WordNetRelation.INSTANCE_HYPERNYM);
@@ -256,6 +259,7 @@ public final class LexicalExpander {
     return all;
   }
 
+  /** Records the candidate under its folded term when not excluded and it beats any current best. */
   private static void offer(Map<String, Expansion> best, Set<String> excluded,
                             Expansion candidate) {
     final String key = fold(candidate.term());
@@ -339,8 +343,8 @@ public final class LexicalExpander {
     }
 
     /**
-     * Configures whether direct hyponyms are included. Hyponyms narrow rather than generalize,
-     * which suits some matching tasks and hurts others, so they are off by default.
+     * Configures whether direct hyponyms are included. They are off by default because they
+     * broaden queries.
      *
      * @param includeHyponyms Whether to include direct hyponyms.
      * @return This builder.