docs: improve javadocs

Author: javier-godoy

src/main/java/com/flowingcode/vaadin/addons/errorwindow/DefaultErrorWindowFactory.java

@@ -21,8 +21,18 @@
 
 package com.flowingcode.vaadin.addons.errorwindow;
 
+/**
+ * Default implementation of {@link ErrorWindowFactory}. Displays error details using an {@link
+ * ErrorWindow}.
+ */
 public class DefaultErrorWindowFactory implements ErrorWindowFactory {
 
+  /**
+   * Displays the error details creating a new instance of {@link ErrorWindow}. The error window is
+   * displayed on the screen by invoking {@link ErrorWindow#open()}.
+   *
+   * @param details the error details to display
+   */
   @Override
   public void showError(ErrorDetails details) {
     ErrorWindow w = new ErrorWindow(details);

src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorDetails.java

@@ -21,29 +21,56 @@
 
 package com.flowingcode.vaadin.addons.errorwindow;
 
+/** Encapsulates error details, including the throwable object and the cause of the error. */
 public class ErrorDetails {
 
   private Throwable throwable;
   private String cause;
 
+  /**
+   * Constructs a new ErrorDetails object with the given throwable and cause.
+   *
+   * @param throwable the throwable object that caused the error
+   * @param cause the cause of the error
+   */
   public ErrorDetails(Throwable throwable, String cause) {
     super();
     this.throwable = throwable;
     this.cause = cause;
   }
 
+  /**
+   * Retrieves the throwable object that caused the error.
+   *
+   * @return the throwable object that caused the error
+   */
   public Throwable getThrowable() {
     return throwable;
   }
 
+  /**
+   * Sets the throwable object that caused the error.
+   *
+   * @param throwable the throwable object that caused the error
+   */
   public void setThrowable(Throwable throwable) {
     this.throwable = throwable;
   }
 
+  /**
+   * Retrieves the cause of the error.
+   *
+   * @return the cause of the error
+   */
   public String getCause() {
     return cause;
   }
 
+  /**
+   * Sets the cause of the error.
+   *
+   * @param cause the cause of the error
+   */
   public void setCause(String cause) {
     this.cause = cause;
   }

src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorManager.java

@@ -26,6 +26,9 @@
 import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Manages errors and displays error messages through different ErrorWindowFactory implementations.
+ */
 public final class ErrorManager {
 
   private static final Map<Class<?>, ErrorWindowFactory> factories = new ConcurrentHashMap<>();
@@ -46,29 +49,64 @@ private ErrorManager() {
     throw new IllegalStateException("Utility class not meant to be instantiated");
   }
 
+  /**
+   * Displays an error message for the given Throwable.
+   *
+   * @param throwable the Throwable object for which the error message should be displayed
+   */
   public static void showError(Throwable throwable) {
     showError(throwable, throwable.getLocalizedMessage());
   }
 
+  /**
+   * Displays an error message for the given Throwable with the specified cause message.
+   *
+   * @param throwable the Throwable object for which the error message should be displayed
+   * @param cause the cause for the error
+   */
   public static void showError(Throwable throwable, String cause) {
     ErrorDetails details = new ErrorDetails(throwable, cause);
     getErrorWindowFactory(throwable.getClass()).showError(details);
   }
 
+  /**
+   * Sets the ErrorWindowFactory for the specified Throwable class.
+   *
+   * @param clazz the class of Throwable for which the ErrorWindowFactory should be set
+   * @param errorWindowFactory the ErrorWindowFactory implementation to be set for the specified
+   *     class
+   */
   public static void setErrorWindowFactory(Class<? extends Throwable> clazz,
       ErrorWindowFactory errorWindowFactory) {
     factories.put(clazz.asSubclass(Throwable.class), errorWindowFactory);
   }
 
+  /**
+   * Gets the ErrorWindowFactory implementation for the specified class or its super classes.
+   *
+   * @param clazz the class for which the ErrorWindowFactory implementation is needed
+   * @return the ErrorWindowFactory implementation associated with the specified class or its super
+   *     classes
+   */
   public static ErrorWindowFactory getErrorWindowFactory(Class<?> clazz) {
     return Optional.ofNullable(factories.get(clazz))
         .orElseGet(() -> getErrorWindowFactory(clazz.getSuperclass()));
   }
 
+  /**
+   * Sets the default ErrorWindowFactory implementation.
+   *
+   * @param errorWindowFactory the default ErrorWindowFactory implementation to be set
+   */
   public static void setErrorWindowFactory(ErrorWindowFactory errorWindowFactory) {
     factories.put(Throwable.class, errorWindowFactory);
   }
 
+  /**
+   * Gets the default ErrorWindowFactory implementation.
+   *
+   * @return the default ErrorWindowFactory implementation
+   */
   public static ErrorWindowFactory getErrorWindowFactory() {
     return getErrorWindowFactory(Throwable.class);
   }

src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorView.java

@@ -27,12 +27,21 @@
 import com.vaadin.flow.router.internal.DefaultErrorHandler;
 import org.apache.http.HttpStatus;
 
+/** View used to display an error message when navigation fails due to an exception. */
 @SuppressWarnings("serial")
 @DefaultErrorHandler
 @javax.annotation.security.PermitAll
 @jakarta.annotation.security.PermitAll
 public class ErrorView extends VerticalLayout implements HasErrorParameter<Exception> {
 
+  /**
+   * This method sets the error parameter to display the error message and returns an HTTP status
+   * code of 500 Internal Server Error.
+   *
+   * @param event a {@code BeforeEnterEvent} object
+   * @param parameter an {@code ErrorParameter} object containing the caught exception
+   * @return an int representing the HTTP status code 500 Internal Server Error
+   */
   @Override
   public int setErrorParameter(BeforeEnterEvent event, ErrorParameter<Exception> parameter) {
     setSizeFull();

src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorWindow.java

@@ -42,10 +42,18 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * Component to visualize an error, caused by an exception, as a modal sub-window. <br>
- * When in production mode it shows a code to report. <br>
+ * Component to visualize an error, caused by an exception, as a modal sub-window. 
+ * When in production mode it shows a code to report. 
  * When in debug mode it allows to visualize the stack trace of the error.
  *
+ * <p>This class has several constructors that allow specifying the cause of the error, an error message, whether the application is in production mode,
+ * and the internationalization of the error message.</p>
+ *
+ * <p>This class also provides constructors that accept an {@link ErrorDetails} instance, which provides additional information about the error.</p>
+ *
+ * <p>A unique identifier is assigned to the dialog window, for use in reporting the error when in production mode.</p>
+ * 
+ * @see ErrorDetails
  * @author pbartolo
  */
 @SuppressWarnings("serial")
@@ -68,29 +76,60 @@ public class ErrorWindow extends Dialog {
 
   private Registration attachListenerRegistration;
 
+  /**
+   * Constructs and initializes an ErrorWindow object with the supplied cause and default production mode and i18n.
+   * @param cause: The cause of the error
+   */
   public ErrorWindow(final Throwable cause) {
     this(cause, null, isProductionMode(), ErrorWindowI18n.createDefault());
   }
 
+  /**
+   * Constructs and initializes an ErrorWindow object with the supplied details and and default production mode.
+   * @param cause: The cause of the error
+   * @param i18n: The internationalization of the ErrorWindow
+   */
   public ErrorWindow(final Throwable cause, final ErrorWindowI18n i18n) {
     this(cause, null, isProductionMode(), i18n);
   }
 
+  /**
+   * Constructs and initializes an ErrorWindow object with the supplied details and default and default production mode and i18n.
+   * @param cause: The cause of the error
+   * @param errorMessage: An optional error message
+   */
   public ErrorWindow(final Throwable cause, final String errorMessage) {
     this(cause, errorMessage, isProductionMode(), ErrorWindowI18n.createDefault());
   }
 
+  /**
+   * Constructs and initializes an ErrorWindow object with the supplied details and default production mode.
+   * @param cause: The cause of the error
+   * @param errorMessage: An optional error message
+   * @param i18n: The internationalization of the ErrorWindow
+   */
   public ErrorWindow(final Throwable cause, final String errorMessage, final ErrorWindowI18n i18n) {
     this(cause, errorMessage, isProductionMode(), i18n);
   }
 
+  /**
+   * Constructs and initializes an ErrorWindow object with the supplied details and default i18n.
+   * @param cause: The cause of the error
+   * @param errorMessage: An optional error message
+   * @param productionMode: The mode in which the Application is running. If true, a code is displayed with error details, else debug information is shown
+   */
   public ErrorWindow(final Throwable cause, final String errorMessage, boolean productionMode) {
     this(cause, errorMessage, productionMode, ErrorWindowI18n.createDefault());
   }
 
-  public ErrorWindow(
-      final Throwable cause,
-      final String errorMessage,
+  /**
+   * Constructs and initializes an ErrorWindow object with the supplied details.
+   * @param cause: The cause of the error
+   * @param errorMessage: An optional error message
+   * @param productionMode: The mode in which the Application is running. If true, a code is displayed with error details, else debug information is shown
+   * @param i18n: The internationalization of the ErrorWindow
+   */
+  public ErrorWindow(final Throwable cause, final String errorMessage,
       boolean productionMode,
       final ErrorWindowI18n i18n) {
     super();
@@ -126,6 +165,12 @@ public ErrorWindow(ErrorDetails errorDetails, boolean productionMode) {
     this(errorDetails.getThrowable(), errorDetails.getCause(), productionMode);
   }
 
+  /**
+   * Constructs and initializes an ErrorWindow object with the supplied error details and internationalization.
+   * This constructor allows for provision of additional information, which is an ErrorDetails object.
+   * @param errorDetails: The ErrorDetails object
+   * @param i18n: The internationalization of the ErrorWindow
+   */
   public ErrorWindow(ErrorDetails errorDetails, final ErrorWindowI18n i18n) {
     this(errorDetails.getThrowable(), errorDetails.getCause(), i18n);
   }

src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorWindowFactory.java

@@ -21,10 +21,21 @@
 
 package com.flowingcode.vaadin.addons.errorwindow;
 
+/** A factory interface for creating error windows. */
 public interface ErrorWindowFactory {
 
+  /**
+   * Shows the error details on a new window.
+   *
+   * @param details the details of the error to be shown
+   */
   void showError(ErrorDetails details);
 
+  /**
+   * Checks whether the application is in production mode.
+   *
+   * @return true if the application is in production mode, false otherwise
+   */
   default boolean isProductionMode() {
     return ("true".equals(System.getProperty("productionMode")));
   }

src/main/java/com/flowingcode/vaadin/addons/errorwindow/ErrorWindowI18n.java

@@ -38,6 +38,7 @@ public class ErrorWindowI18n {
   private String defaultErrorMessage;
   private String clipboard;
 
+  /** Constructor for creating the default instance of the object. */
   private ErrorWindowI18n() {
     this.caption = "An error has occurred";
     this.instructions = "Please report the following code to your system administrator";
@@ -47,6 +48,11 @@ private ErrorWindowI18n() {
     this.clipboard = "Copy details to clipboard";
   }
 
+  /**
+   * Constructor for creating an instance of the object from a message translator function.
+   *
+   * @param i18nTranslator a message translation function.
+   */
   private ErrorWindowI18n(SerializableFunction<String, String> i18nTranslator) {
     this.caption = i18nTranslator.apply("com.flowingcode.vaadin.addons.errorwindow.caption");
     this.instructions =
@@ -58,11 +64,21 @@ private ErrorWindowI18n(SerializableFunction<String, String> i18nTranslator) {
     this.clipboard = i18nTranslator.apply("com.flowingcode.vaadin.addons.errorwindow.clipboard");
   }
 
-  /** @return a new instance with the default messages */
+  /**
+   * Creates a new instance with the default messages.
+   *
+   * @return a new instance with the default messages
+   */
   public static ErrorWindowI18n createDefault() {
     return new ErrorWindowI18n();
   }
 
+  /**
+   * Creates a new instance with the provided message translation function.
+   *
+   * @param i18nTranslator a message translation function.
+   * @return a new instance with the provided message translation function.
+   */
   public static ErrorWindowI18n create(SerializableFunction<String, String> i18nTranslator) {
     return new ErrorWindowI18n(i18nTranslator);
   }

src/main/java/com/flowingcode/vaadin/addons/errorwindow/I18nErrorWindowFactory.java

@@ -21,14 +21,25 @@
 
 package com.flowingcode.vaadin.addons.errorwindow;
 
+/** A factory class to create an error window with internationalization support */
 public class I18nErrorWindowFactory implements ErrorWindowFactory {
 
   private final ErrorWindowI18n errorWindowI18n;
-  
-  I18nErrorWindowFactory(ErrorWindowI18n errorWindowI18n){
+
+  /**
+   * Constructs a new I18nErrorWindowFactory instance with a given ErrorWindowI18n instance
+   *
+   * @param errorWindowI18n the ErrorWindowI18n instance to be used
+   */
+  I18nErrorWindowFactory(ErrorWindowI18n errorWindowI18n) {
     this.errorWindowI18n = errorWindowI18n;
   }
-  
+
+  /**
+   * Shows an error window with the given error details and internationalization support
+   *
+   * @param details the ErrorDetails instance to be shown in the error window
+   */
   @Override
   public void showError(ErrorDetails details) {
     new ErrorWindow(details, errorWindowI18n).open();

src/main/java/com/flowingcode/vaadin/addons/errorwindow/VaadinServiceInitListenerImpl.java

@@ -31,10 +31,21 @@
 import com.vaadin.flow.server.startup.ApplicationRouteRegistry;
 import java.util.Collections;
 
+/**
+ * Implementation of {@code VaadinServiceInitListener} interface. This class adds a session init
+ * listener to the Vaadin service, sets an error handler and registers an error view.
+ */
 public class VaadinServiceInitListenerImpl implements VaadinServiceInitListener {
 
   private static final long serialVersionUID = 1L;
 
+  /**
+   * Implements the {@code serviceInit} method from {@code VaadinServiceInitListener} interface.
+   * This method sets {@code ErrorManager} as the error handler and registers {@link ErrorView} as
+   * the default error view.
+   *
+   * @param event The ServiceInitEvent to be handled.
+   */
   @Override
   public void serviceInit(ServiceInitEvent event) {
     event
@@ -43,6 +54,11 @@ public void serviceInit(ServiceInitEvent event) {
     registerErrorView(event.getSource());
   }
 
+  /**
+   * Registers an error view to the Vaadin service.
+   *
+   * @param service The Vaadin service to which the error view needs to be registered.
+   */
   private void registerErrorView(VaadinService source) {
     VaadinContext context = VaadinService.getCurrent().getContext();
     ApplicationRouteRegistry registry = ApplicationRouteRegistry.getInstance(context);