GEODE-10023: Fix javadocs (#7594)

This commit reduces the number of errors reported in the gradle build
log due to javadocs from over 3000 to 0. It also reduces the number of
warnings reported in the gradle build log due to javadocs from over
4000 to 0.

After these changes, all published javadocs are now syntactically
correct, although no guarantee is made as to the content of the
documentation. Javadocs in classes that did not produce warnings or
errors in the gradle build log were not touched.

For classes in the geode-dunit, geode-junit, geode-assembly and
geode-concurrency-test modules, if a javadoc could be converted to
a non-javadoc comment without losing any formatting or tags, it was
converted, since those classes are not intended for use by Geode users

The changes made were:
 - Add missing @return, @param and @throws tags
 - Fix all errors due to incorrect HTML
 - Fix all errors due to improperly escaped characters
 - Fix all broken @link tags
 - Several minor spelling errors and typos fixed where spotted

In addition to this clean-up, the compiler settings were modified so
that javadocs warnings and errors will be output in the gradle build 
log, and if any are present, the build will fail.

Authored-by: Donal Evans <[email protected]>
Co-authored-by: Patrick Johnson <[email protected]>

extensions/geode-modules-session-internal/src/main/java/org/apache/geode/modules/session/internal/common/CacheProperty.java

@@ -37,14 +37,14 @@ public enum CacheProperty {
   /**
    * This parameter can take the following values which match the respective attribute container
    * classes
-   * <p/>
+   * <p>
    * delta_queued : QueuedDeltaSessionAttributes delta_immediate : DeltaSessionAttributes
    */
   SESSION_DELTA_POLICY(String.class),
 
   /**
    * This parameter can take the following values:
-   * <p/>
+   * <p>
    * set (default) set_and_get
    */
   REPLICATION_TRIGGER(String.class);

extensions/geode-modules-session/src/main/java/org/apache/geode/modules/session/filter/SessionCachingFilter.java

@@ -541,6 +541,8 @@ private static String getStackTrace(Throwable t) {
 
   /**
    * Retrieve the SessionManager. This is only here so that tests can get access to the cache.
+   *
+   * @return the SessionManager
    */
   public static SessionManager getSessionManager() {
     return manager;

extensions/geode-modules-test/src/main/java/org/apache/geode/modules/session/AbstractSessionsTest.java

@@ -113,7 +113,7 @@ private WebRequest prepareRequest(final String key, final String value) {
     return req;
   }
 
-  /**
+  /*
    * Check that the basics are working
    */
   @Test
@@ -127,7 +127,7 @@ public void testSanity() throws Exception {
     assertEquals("JSESSIONID", response.getNewCookieNames()[0]);
   }
 
-  /**
+  /*
    * Test callback functionality. This is here really just as an example. Callbacks are useful to
    * implement per test actions which can be defined within the actual test method instead of in a
    * separate servlet class.
@@ -144,7 +144,7 @@ public void testCallback() throws Exception {
     assertEquals(helloWorld, response.getText());
   }
 
-  /**
+  /*
    * Test that calling session.isNew() works for the initial as well as subsequent requests.
    */
   @Test
@@ -168,7 +168,7 @@ public void testIsNew() throws Exception {
     assertEquals("false", response.getText());
   }
 
-  /**
+  /*
    * Check that our session persists. The values we pass in as query params are used to set
    * attributes on the session.
    */
@@ -193,7 +193,7 @@ public void testSessionPersists1() throws Exception {
     assertEquals(value, response.getText());
   }
 
-  /**
+  /*
    * Test that invalidating a session makes it's attributes inaccessible.
    */
   @Test
@@ -219,7 +219,7 @@ public void testInvalidate() throws Exception {
     assertEquals("", response.getText());
   }
 
-  /**
+  /*
    * Test setting the session expiration
    */
   @Test
@@ -259,7 +259,7 @@ public void testSessionExpiration2() {
     assertEquals(60, sessionManager.getMaxInactiveInterval());
   }
 
-  /**
+  /*
    * Test expiration of a session by the tomcat container, rather than gemfire expiration
    */
   @Test
@@ -288,7 +288,7 @@ public void testSessionExpirationByContainer() throws Exception {
     assertEquals("", response.getText());
   }
 
-  /**
+  /*
    * Test that removing a session attribute also removes it from the region
    */
   @Test
@@ -314,7 +314,7 @@ public void testRemoveAttribute() throws Exception {
     assertNull(region.get(sessionId).getAttribute(key));
   }
 
-  /**
+  /*
    * Test that a session attribute gets set into the region too.
    */
   @Test
@@ -330,7 +330,7 @@ public void testBasicRegion() throws Exception {
     assertEquals(value, region.get(sessionId).getAttribute(key));
   }
 
-  /**
+  /*
    * Test that a session attribute gets removed from the region when the session is invalidated.
    */
   @Test
@@ -352,7 +352,7 @@ public void testRegionInvalidate() throws Exception {
     assertNull("The region should not have an entry for this session", region.get(sessionId));
   }
 
-  /**
+  /*
    * Test that multiple attribute updates, within the same request result in only the latest one
    * being effective.
    */
@@ -386,7 +386,7 @@ public void testCommitSessionValveInvalidSession() throws Exception {
     assertEquals("done", response.getText());
   }
 
-  /**
+  /*
    * Test for issue #45 Sessions are being created for every request
    */
   @Test
@@ -401,7 +401,7 @@ public void testExtraSessionsNotCreated() throws Exception {
     assertEquals("The region should be empty", 0, region.size());
   }
 
-  /**
+  /*
    * Test for issue #46 lastAccessedTime is not updated at the start of the request, but only at the
    * end.
    */

extensions/geode-modules/src/main/java/org/apache/geode/modules/session/catalina/AbstractCacheLifecycleListener.java

@@ -32,6 +32,9 @@ public void lifecycleEvent(LifecycleEvent le) {
 
   /**
    * This is called by Tomcat to set properties on the Listener.
+   *
+   * @param name the name of the property to set
+   * @param value the value to set the property to
    */
   public void setProperty(String name, String value) {
     cache.setProperty(name, value);

extensions/geode-modules/src/main/java/org/apache/geode/modules/session/catalina/AbstractCommitSessionValve.java

@@ -53,6 +53,7 @@ public void invoke(final Request request, final Response response)
   /**
    * Commit session only if DeltaSessionManager is in place.
    *
+   * @param <SelfT> the type of AbstractCommitSessionValve being used by the DeltaSessionManager
    * @param request to commit session from.
    */
   protected static <SelfT extends AbstractCommitSessionValve<?>> void commitSession(

extensions/geode-modules/src/main/java/org/apache/geode/modules/session/catalina/DeltaSessionManager.java

@@ -631,7 +631,6 @@ protected void unregisterCommitSessionValve() {
    * session timeout value specified in the web.xml.
    * <p>
    * The precedence order for setting the session timeout value is:
-   * <p>
    * <ol>
    * <li>the max inactive interval is set based on the Manager defined in the context.xml
    * <li>the max inactive interval is then overwritten by the value of the Context's session timeout

extensions/geode-modules/src/main/java/org/apache/geode/modules/session/catalina/DeltaSessionManagerConfiguration.java

@@ -60,12 +60,16 @@ interface DeltaSessionManagerConfiguration {
   boolean isBackingCacheAvailable();
 
   /**
+   * @param enable boolean specifying whether to prefer deserialized form
+   *
    * @deprecated No replacement. Always prefer deserialized form.
    */
   @Deprecated
   void setPreferDeserializedForm(boolean enable);
 
   /**
+   * @return whether to prefer deserialized form
+   *
    * @deprecated No replacement. Always prefer deserialized form.
    */
   @Deprecated

extensions/geode-modules/src/main/java/org/apache/geode/modules/session/catalina/SessionManager.java

@@ -39,6 +39,8 @@ public interface SessionManager {
   boolean isBackingCacheAvailable();
 
   /**
+   * @return whether to prefer deserialized form
+   *
    * @deprecated no replacement. Always prefer deserialized form.
    */
   @Deprecated

geode-assembly/build.gradle

@@ -384,7 +384,7 @@ tasks.register('gfshDepsJar', Jar) {
 
 tasks.register('docs', Javadoc) {
   def docsDir = file("$buildDir/javadocs")
-  options.addStringOption('Xdoclint:none', '-quiet')
+  options.addStringOption('Xwerror', '-quiet')
   options.links("https://docs.oracle.com/javase/8/docs/api/")
   options.encoding = 'UTF-8'
   title = "${productName} ${project.version}"

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/Customer.java

@@ -24,7 +24,7 @@
 
 /**
  * The Customer class models a customer entity.
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/Gender.java

@@ -16,7 +16,7 @@
 
 /**
  * The Gender enum is a enumeration of genders (sexes).
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/GetAllEntries.java

@@ -22,7 +22,7 @@
 
 /**
  * The GetAllEntries is function that will return a map as a result of its execution.
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/GetDeliveredOrders.java

@@ -34,7 +34,7 @@
 
 /**
  * The GetDeliveredOrders class is a gemfire function that gives details about delivered orders.
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/GetRegions.java

@@ -26,7 +26,7 @@
 
 /**
  * The GetRegions class is an gemfire function that gives data about available regions.
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/Item.java

@@ -22,7 +22,7 @@
 
 /**
  * The Item class models item entity in the real world.
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/NoArgumentFunction.java

@@ -33,11 +33,10 @@ public class NoArgumentFunction implements Function {
    * <p>
    * If {@link Function#hasResult()} returns false, {@link ResultCollector#getResult()} throws
    * {@link FunctionException}.
-   * </p>
    * <p>
    * If {@link Function#hasResult()} returns true, {@link ResultCollector#getResult()} blocks and
    * waits for the result of function execution
-   * </p>
+   * <p>
    *
    * @return whether this function returns a Result back to the caller.
    *
@@ -81,18 +80,18 @@ public String getId() {
    * Return true to indicate to GemFire the method requires optimization for writing the targeted
    * {@link FunctionService#onRegion(Region)} and any associated
    * {@linkplain Execution#withFilter(Set) routing objects}.
-   * </p>
+   * <p>
    *
    * <p>
    * Returning false will optimize for read behavior on the targeted
    * {@link FunctionService#onRegion(Region)} and any associated
    * {@linkplain Execution#withFilter(Set) routing objects}.
-   * </p>
+   * <p>
    *
    * <p>
    * This method is only consulted when Region passed to
    * FunctionService#onRegion(org.apache.geode.cache.Region) is a partitioned region
-   * </p>
+   * <p>
    *
    * @return false if the function is read only, otherwise returns true
    *

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/Order.java

@@ -24,7 +24,7 @@
 
 /**
  * The Order class is an abstraction modeling a order.
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */

geode-assembly/geode-assembly-test/src/main/java/org/apache/geode/rest/internal/web/controllers/Person.java

@@ -23,7 +23,7 @@
 
 /**
  * The Person class is an abstraction modeling a person.
- * <p/>
+ * <p>
  *
  * @since GemFire 8.0
  */