From 606476f869de5f478bb299ed404ad95150582b1d Mon Sep 17 00:00:00 2001
From: Steve Jones <steve@squaregoldfish.co.uk>
Date: Fri, 29 Nov 2024 17:46:29 +0100
Subject: [PATCH] JavaDoc

---
 .../ac/exeter/QuinCe/TestBase/BaseTest.java   | 32 ++++++++++++-------
 .../ac/exeter/QuinCe/web/BaseManagedBean.java |  5 +--
 .../ac/exeter/QuinCe/web/BeanException.java   | 17 ++++++++--
 3 files changed, 39 insertions(+), 15 deletions(-)

diff --git a/WebApp/junit/uk/ac/exeter/QuinCe/TestBase/BaseTest.java b/WebApp/junit/uk/ac/exeter/QuinCe/TestBase/BaseTest.java
index 7ced602dc..caf21917b 100644
--- a/WebApp/junit/uk/ac/exeter/QuinCe/TestBase/BaseTest.java
+++ b/WebApp/junit/uk/ac/exeter/QuinCe/TestBase/BaseTest.java
@@ -51,9 +51,6 @@
  * Additional custom migrations for specific tests can be defined using
  * {@code @FlywayTest locationsForMigrate = {"resources/sql/..."}}.
  * </p>
- *
- * @author Steve Jones
- *
  */
 @ExtendWith(SpringExtension.class)
 @ContextConfiguration(locations = { "/resources/context/testContext.xml" })
@@ -62,25 +59,31 @@
 public class BaseTest {
 
   /**
-   * A global application context
+   * A global application context.
    */
   @Autowired
   protected ApplicationContext context;
 
   /**
-   * A mock Servlet Context
+   * A mock Servlet Context.
    */
   @Mock
   protected static ServletContext servletContext;
 
+  /**
+   * A mock Java Server Faces context.
+   */
   @Mock
   protected static FacesContext facesContext;
 
+  /**
+   * A mock External Context.
+   */
   @Mock
   protected static ExternalContext externalContext;
 
   /**
-   * A mock Servlet Context Event
+   * A mock Servlet Context Event.
    */
   @Mock
   protected static ServletContextEvent servletContextEvent;
@@ -139,10 +142,10 @@ public void initResourceManager() {
   }
 
   /**
-   * Get a data source linked to the H2 test database defined in the
-   * {@link #context}.
+   * Get a {@link DataSource} linked to the H2 test database defined in the
+   * {@link #context}, that can be used to obtain database {@link Connection}s.
    *
-   * @return A data source
+   * @return A {@link DataSource}.
    */
   protected DataSource getDataSource() {
     return (DataSource) context.getBean("dataSourceRef");
@@ -160,12 +163,13 @@ protected Connection getConnection() throws SQLException {
   }
 
   /**
-   * Create a {@link Stream} of {@code null} and empty String values
+   * Create a {@link Stream} of {@code null} and empty String values.
    *
    * <p>
    * Some tests need to check behaviours with empty {@link String} values. This
    * method provides a {@link Stream} of empty {@link String}s that can be used
-   * as input to a {@link ParameterizedTest}.
+   * as input to a {@link ParameterizedTest}, including whitespace and
+   * {@code null} values.
    * </p>
    *
    * @return A {@link Stream} of various empty {@link String} values.
@@ -174,6 +178,12 @@ protected static Stream<String> createNullEmptyStrings() {
     return Stream.of(null, "", " ", "  ", "\t", "\n");
   }
 
+  /**
+   * Creates a simple {@link Stream} containing the two possible {@code boolean}
+   * values.
+   *
+   * @return A {@link Stream} of boolean values.
+   */
   protected static Stream<Boolean> booleans() {
     return Stream.of(true, false);
   }
diff --git a/WebApp/src/uk/ac/exeter/QuinCe/web/BaseManagedBean.java b/WebApp/src/uk/ac/exeter/QuinCe/web/BaseManagedBean.java
index b38840e2d..ee05d44e1 100644
--- a/WebApp/src/uk/ac/exeter/QuinCe/web/BaseManagedBean.java
+++ b/WebApp/src/uk/ac/exeter/QuinCe/web/BaseManagedBean.java
@@ -269,9 +269,10 @@ public String getUrlStub() {
   }
 
   /**
-   * Get a data source from which database connections can be obtained.
+   * Get a {@link DataSource} from which database {@link java.sql.Connection}s
+   * can be obtained.
    *
-   * @return The data source.
+   * @return A {@link DataSource}.
    */
   public DataSource getDataSource() {
     return ResourceManager.getInstance().getDBDataSource();
diff --git a/WebApp/src/uk/ac/exeter/QuinCe/web/BeanException.java b/WebApp/src/uk/ac/exeter/QuinCe/web/BeanException.java
index d159a1749..dcc375a75 100644
--- a/WebApp/src/uk/ac/exeter/QuinCe/web/BeanException.java
+++ b/WebApp/src/uk/ac/exeter/QuinCe/web/BeanException.java
@@ -1,17 +1,30 @@
 package uk.ac.exeter.QuinCe.web;
 
 /**
- * Exception class for miscellaneous errors in beans
+ * Exception class for miscellaneous errors in beans.
  */
 @SuppressWarnings("serial")
 public class BeanException extends Exception {
 
+  /**
+   * Constructor for a basic error with just a message.
+   *
+   * @param message
+   *          The error message.
+   */
   public BeanException(String message) {
     super(message);
   }
 
+  /**
+   * Constructor for an error with a message and an underlying cause.
+   *
+   * @param message
+   *          The error message.
+   * @param cause
+   *          The underlying cause.
+   */
   public BeanException(String message, Throwable cause) {
     super(message, cause);
   }
-
 }