#287 - Reduce JavaDoc warnings for jwpl-api to zero

- applies fixes to many api classes and interfaces to clear out hundreds of warnings - removes (super) dead and worthless code from several very long classes (along the path) Fixes #287
dkpro · Dec 1, 2023 · eaa0516 · eaa0516
1 parent 6fef05f
commit eaa0516
Show file tree

Hide file tree

Showing 49 changed files with 1,053 additions and 433 deletions.
diff --git a/dkpro-jwpl-api/pom.xml b/dkpro-jwpl-api/pom.xml
@@ -182,6 +182,16 @@
       </resource>
     </resources>
     <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <configuration>
+          <sourceFileExcludes>
+            <!-- exclude this specific file to avoid creating useless enum value javadoc for languages -->
+            <sourceFileExclude>org/dkpro/jwpl/api/WikiConstants.java</sourceFileExclude>
+          </sourceFileExcludes>
+        </configuration>
+      </plugin>
       <plugin>
         <groupId>org.codehaus.mojo</groupId>
         <artifactId>build-helper-maven-plugin</artifactId>

diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Category.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/Category.java
@@ -28,6 +28,16 @@
 import org.hibernate.Session;
 import org.hibernate.type.StandardBasicTypes;
 
+/**
+ * Represents a category as conceptually defined by Wikipedia.
+ * Each category can group several {@link Page pages}.
+ * <p>
+ * It can be subdivided further, that is, every category can have descendents or siblings.
+ * Structurally, Wikipedia defined categories to be represented as a graph. Consequently,
+ * a category can have multiple parent categories.
+ *
+ * @see Page
+ */
 public class Category
     implements WikiConstants
 {
@@ -383,6 +393,10 @@ public Iterable<Category> getDescendants()
     /**
      * Returns *all* recursively collected descendants (=subcategories) of this category.
      *
+     * @param bufferSize The size of the page buffer. With {@code bufferSize = 1}, a database connection is needed for
+     *                   retrieving a single article. Higher {@code bufferSize} values gives better performance,
+     *                   but require more memory. Must not be less or equal to {@code 0}.
+     *
      * @return An iterable of all descendants (=subcategories) of this category.
      */
     protected Iterable<Category> getDescendants(int bufferSize)

diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterable.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterable.java
@@ -36,12 +36,26 @@ public class CategoryDescendantsIterable
      */
     private int bufferSize = 25;
 
+    /**
+     * Initializes a {@link CategoryDescendantsIterable} instance. Uses a default buffer size of {@code 25}.
+     *
+     * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}.
+     * @param startCategory The Wikipedia category to start descending from. Must not be {@code null}.
+     */
     public CategoryDescendantsIterable(Wikipedia wiki, Category startCategory)
     {
         this.wiki = wiki;
         this.startCategory = startCategory;
     }
 
+    /**
+     * Initializes a {@link CategoryDescendantsIterable} instance.
+     *
+     * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}.
+     * @param bufferSize The number of pages to be buffered after a query to the database.
+     *                   Higher bufferSize gives better performance, but require more memory.
+     * @param startCategory The Wikipedia category to start descending from. Must not be {@code null}.
+     */
     public CategoryDescendantsIterable(Wikipedia wiki, int bufferSize, Category startCategory)
     {
         this.wiki = wiki;

diff --git a/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterator.java b/dkpro-jwpl-api/src/main/java/org/dkpro/jwpl/api/CategoryDescendantsIterator.java
@@ -52,6 +52,14 @@ public class CategoryDescendantsIterator
      */
     private final Set<Integer> expandedCategoryIds;
 
+    /**
+     * Initializes a {@link CategoryDescendantsIterator} instance.
+     *
+     * @param wiki A valid, full initialized {@link Wikipedia} instance. Must not be {@code null}.
+     * @param bufferSize The number of pages to be buffered after a query to the database.
+     *                   Higher bufferSize gives better performance, but require more memory.
+     * @param startCategory The Wikipedia category to start descending from. Must not be {@code null}.
+     */
     public CategoryDescendantsIterator(Wikipedia wiki, int bufferSize, Category startCategory)
     {
         this.wiki = wiki;