Heavily improve API doc of EngineConfiguration class

base/src/main/java/de/staropensource/engine/base/EngineConfiguration.java

@@ -19,8 +19,11 @@
 
 package de.staropensource.engine.base;
 
+import de.staropensource.engine.base.annotation.EngineSubsystem;
+import de.staropensource.engine.base.event.LogEvent;
 import de.staropensource.engine.base.implementable.Configuration;
 import de.staropensource.engine.base.implementable.ShortcodeParser;
+import de.staropensource.engine.base.implementable.SubsystemClass;
 import de.staropensource.engine.base.logging.Logger;
 import de.staropensource.engine.base.logging.backend.async.LoggingThread;
 import de.staropensource.engine.base.type.EngineState;
@@ -66,11 +69,11 @@ public final class EngineConfiguration extends Configuration {
     private static EngineConfiguration instance;
 
     /**
-     * Contains prefix properties must begin with.
+     * Contains the configuration prefix.
      *
      * @since v1-alpha0
      * -- GETTER --
-     * Returns prefix properties must begin with.
+     * Returns the configuration prefix.
      *
      * @return property group
      * @since v1-alpha0
@@ -79,132 +82,196 @@ public final class EngineConfiguration extends Configuration {
 
 
     /**
-     * If enabled, allows for unintentional behaviour
+     * Contains if debugging options should be allowed.
-     * and excess logging. Unless you want to debug or work
+     * All debugging options will be forcefully set to
-     * on a sensitive part of the engine, don't enable this!
+     * {@code false} if this option is set to {@code false}.
      *
      * @since v1-alpha0
      * -- GETTER --
-     * Gets the value for {@link #debug}.
+     * Returns if debugging options should be allowed.
+     * All debugging options will be forcefully set to
+     * {@code false} if this option is set to {@code false}.
      *
-     * @return variable value
+     * @return debugging enabled?
-     * @see #debug
      * @since v1-alpha0
      */
     private boolean debug;
 
     /**
-     * If enabled, all called events will be logged.
+     * Contains whether or not to log
+     * events being emitted.
+     * <p>
+     * This will cause all events to
+     * be logged, with the exception
+     * of the {@link LogEvent}.
      *
      * @since v1-alpha0
      * -- GETTER --
-     * Gets the value for {@link #debugEvents}.
+     * Returns whether or not to log
+     * events being emitted.
+     * <p>
+     * This will cause all events to
+     * be logged, with the exception
+     * of the {@link LogEvent}.
      *
-     * @return variable value
+     * @return detailed event logging enabled?
-     * @see #debugEvents
      * @since v1-alpha0
      */
     private boolean debugEvents;
 
 
     /**
-     * If enabled, will try to automatically initialize every
+     * Contains whether or not to automatically discover
-     * subsystem found though reflection.
+     * and initialize any class extending {@link SubsystemClass}
+     * whilst being annotated with {@link EngineSubsystem}.
      * <p>
-     * This however may fail in certain situation, where manual
+     * This mechanism may fail in certain situations, where
-     * subsystem initialization may be required. For this reason,
+     * manual subsystem initialization may be desired. Make
-     * this can be turned off before the engine initializes. Please
+     * sure to disable this setting before engine startup
-     * note though that dependency resolution between subsystems
+     * and then initialize all subsystems manually.
-     * won't be performed, be careful when initializing subsystems manually.
      *
      * @see Engine
-     * @since v1-alpha2
+     * @since v1-alpha5
      * -- GETTER --
-     * Gets the value for {@link #initialPerformSubsystemInitialization}.
+     * Returns whether or not to automatically discover
+     * and initialize any class extending {@link SubsystemClass}
+     * whilst being annotated with {@link EngineSubsystem}.
+     * <p>
+     * This mechanism may fail in certain situations, where
+     * manual subsystem initialization may be desired. Make
+     * sure to disable this setting before engine startup
+     * and then initialize all subsystems manually.
      *
-     * @return variable value
+     * @return automatically discover and initialize subsystems?
-     * @see #initialPerformSubsystemInitialization
      * @since v1-alpha5
      */
     private boolean initialPerformSubsystemInitialization;
 
     /**
-     * Will try to load the specified classes as subsystems,
+     * Contains a set of class names to try to load
-     * if reflective classpath scanning is disabled.
+     * and initialize as subsystems. Will only take effect
+     * if {@link #initialPerformSubsystemInitialization} is
+     * turned off.
      *
      * @since v1-alpha5
      * -- GETTER --
-     * Gets the value for {@link #initialIncludeSubsystemClasses}.
+     * Returns a set of class names to try to load
+     * and initialize as subsystems. Will only take effect
+     * if {@link #getInitialIncludeSubsystemClasses()} is
+     * turned off.
      *
-     * @return variable value
+     * @return set of class names to try and initialize as subsystems
-     * @see #initialIncludeSubsystemClasses
      * @since v1-alpha5
      */
     private Set<@NotNull String> initialIncludeSubsystemClasses;
 
 
     /**
-     * If enabled, will cause {@link ShortcodeParser} to print
+     * Contains whether or not to complain about invalid
-     * invalid shortcodes as {@link LogLevel#SILENT_WARNING}s.
+     * shortcodes.
+     * <p>
+     * Requires the active log level to be set at least
+     * to {@link LogLevel#SILENT_WARNING} to have effect.
      *
-     * @see ShortcodeParser
      * @see #logLevel
      * @since v1-alpha0
      * -- GETTER --
-     * Gets the value for {@link #errorShortcodeParser}.
+     * Returns whether or not to complain about invalid
+     * shortcodes.
+     * <p>
+     * Requires the active log level to be set at least
+     * to {@link LogLevel#SILENT_WARNING} to have effect.
      *
-     * @return variable value
+     * @return complain about invalid shortcodes?
-     * @see #errorShortcodeParser
+     * @see #getLogLevel()
      * @since v1-alpha0
      */
     private boolean errorShortcodeParser;
 
 
     /**
-     * If enabled, will makes the {@link Logger} work asynchronous,
+     * Contains if to log asynchronously.
-     * in a separate platform thread. Don't disable unless you want
+     * <p>
-     * your application to run <b>extremely</b> slowly.
+     * If enabled, will cause a logging thread
+     * to spawn. All log messages will be queued
+     * and printed after a set delay
+     * ({@link #logPollingSpeed}).
+     * Highly recommended to keep enabled, or
+     * the performance of your application will
+     * very likely suffer.
      *
      * @see #logPollingSpeed
-     * @see Thread
      * @since v1-alpha0
      * -- GETTER --
-     * Gets the value for {@link #optimizeLogging}.
+     * Returns if to log asynchronously.
+     * <p>
+     * If enabled, will cause a logging thread
+     * to spawn. All log messages will be queued
+     * and printed after a set delay
+     * ({@link #getLogPollingSpeed()}).
+     * Highly recommended to keep enabled, or
+     * the performance of your application will
+     * very likely suffer.
      *
-     * @return variable value
+     * @return log asynchronously?
-     * @see #optimizeLogging
+     * @see #getLogPollingSpeed()
      * @since v1-alpha0
      */
     private boolean optimizeLogging;
 
     /**
-     * If enabled, will make all events asynchronous,
+     * Contains whether or not to emit events
-     * in separate virtual threads. Don't disable unless you
+     * asynchronously.
-     * want your application to run slower.
+     * <p>
+     * This will cause a
+     * <a href="https://openjdk.org/jeps/444">VirtualThread</a>
+     * to spawn every time an event is emitted.
      *
-     * @see VirtualThread
      * @since v1-alpha0
      * -- GETTER --
-     * Gets the value for {@link #optimizeEvents}.
+     * Contains whether or not to emit events
+     * asynchronously.
+     * <p>
+     * This will cause a
+     * <a href="https://openjdk.org/jeps/444">VirtualThread</a>
+     * to spawn every time an event is emitted.
      *
-     * @return variable value
+     * @return emit events asynchronously?
-     * @see #optimizeEvents
      * @since v1-alpha0
      */
     private boolean optimizeEvents;
 
 
     /**
-     * Contains which logger levels are allowed
+     * Contains the minimum allowed log level.
-     * by setting the minimum logger level.
+     * <p>
+     * The priority list is as follows (from high to low priority):
+     * <ul>
+     *     <li>{@link LogLevel#CRASH}</li>
+     *     <li>{@link LogLevel#ERROR}</li>
+     *     <li>{@link LogLevel#WARNING}</li>
+     *     <li>{@link LogLevel#INFORMATIONAL}</li>
+     *     <li>{@link LogLevel#SILENT_WARNING}</li>
+     *     <li>{@link LogLevel#VERBOSE}</li>
+     *     <li>{@link LogLevel#DIAGNOSTIC}</li>
+     * </ul>
      *
-     * @see Logger
      * @since v1-alpha0
      * -- GETTER --
-     * Gets the value for {@link #logLevel}.
+     * Returns the minimum allowed log level.
+     * <p>
+     * The priority list is as follows (from high to low priority):
+     * <ul>
+     *     <li>{@link LogLevel#CRASH}</li>
+     *     <li>{@link LogLevel#ERROR}</li>
+     *     <li>{@link LogLevel#WARNING}</li>
+     *     <li>{@link LogLevel#INFORMATIONAL}</li>
+     *     <li>{@link LogLevel#SILENT_WARNING}</li>
+     *     <li>{@link LogLevel#VERBOSE}</li>
+     *     <li>{@link LogLevel#DIAGNOSTIC}</li>
+     * </ul>
      *
-     * @return variable value
+     * @return minimum allowed log level
-     * @see #logLevel
      * @since v1-alpha0
      */
     private LogLevel logLevel;
@@ -226,75 +293,118 @@ public final class EngineConfiguration extends Configuration {
      *     <li><code>lineNumber</code></li>
      * </ul>
      *
-     * @see Logger
      * @since v1-alpha8
      * -- GETTER --
-     * Gets the value for {@link #logFeatures}
+     * Returns a comma-separated list of optional
+     * features to add to the final log output.
+     * <p>
+     * Available features (in order of appearance):
+     * <ul>
+     *     <li><code>formatting</code></li>
+     *     <li><code>runtime</code></li>
+     *     <li><code>date</code></li>
+     *     <li><code>time</code></li>
+     *     <li><code>shortIssuerClass</code></li>
+     *     <li><code>moduleName</code></li>
+     *     <li><code>moduleVersion</code> (requires <code>moduleName</code>)</li>
+     *     <li><code>methodName</code></li>
+     *     <li><code>lineNumber</code></li>
+     * </ul>
      *
-     * @return variable value
+     * @return optional features to enable
-     * @see #logFeatures
      * @since v1-alpha8
      */
     private Set<@NotNull String> logFeatures;
 
     /**
      * Contains how fast the logging thread will
-     * poll for queued messages. This also causes
+     * poll for queued messages in milliseconds.
-     * messages to be buffered.
+     * This also causes messages to be buffered.
      * <p>
      * Only applies if {@code optimizeLogging} is turned on.
-     * Values below {@code 1} will poll for queued
+     * Values below {@code 1} will poll for queued messages
-     * messages as fast as it can. This however has pretty much
+     * as fast as it can. This however has pretty much no
-     * no benefit. Leave it at {@code 5}, it works quite well.
+     * benefit. Leave it at {@code 5}, it works quite well.
      *
      * @see #optimizeLogging
      * @since v1-alpha4
      * -- GETTER --
-     * Gets the value for {@link #logPollingSpeed}.
+     * Contains how fast the logging thread will
+     * poll for queued messages, in milliseconds.
+     * This also causes messages to be buffered.
+     * <p>
+     * Only applies if {@code optimizeLogging} is turned on.
+     * Values below {@code 1} will poll for queued messages
+     * as fast as it can. This however has pretty much no
+     * benefit. Leave it at {@code 5}, it works quite well.
      *
-     * @return variable value
+     * @return logging thread polling speed in milliseconds
-     * @see #logPollingSpeed
+     * @see #isOptimizeLogging()
      * @since v1-alpha4
      */
     private int logPollingSpeed;
 
     /**
-     * If enabled, will force sos!engine's logging infrastructure to use
+     * Contains whether or not to forcefully write
-     * <a href="https://www.man7.org/linux/man-pages/man3/stderr.3.html">the standard output</a>
+     * to the standard output instead of the
-     * instead of <a href="https://www.man7.org/linux/man-pages/man3/stderr.3.html">the standard error</a>
+     * standard error stream.
-     * for logging the {@code ERROR} and {@code CRASH} log levels.
+     * <p>
+     * This only applies to the {@link LogLevel#ERROR} and
+     * {@link LogLevel#CRASH} log levels, as these use
+     * the standard error stream by default.
      *
+     * @see <a href="https://man7.org/linux/man-pages/man3/stderr.3.html">man page about standard streams</a>
      * @since v1-alpha0
      * -- GETTER --
-     * Gets the value for {@link #logForceStandardOutput}.
+     * Contains whether or not to forcefully write
+     * to the standard output instead of the
+     * standard error stream.
+     * <p>
+     * This only applies to the {@link LogLevel#ERROR} and
+     * {@link LogLevel#CRASH} log levels, as these use
+     * the standard error stream by default.
      *
-     * @return variable value
+     * @return force use stdout?
-     * @see #logForceStandardOutput
+     * @see <a href="https://man7.org/linux/man-pages/man3/stderr.3.html">man page about standard streams</a>
      * @since v1-alpha0
      */
     private boolean logForceStandardOutput;
 
 
     /**
-     * Will truncate the path of types when using
+     * Contains if to truncate the full path
-     * their {@code toString} method.
+     * of a class when invoking using their
+     * {@link #toString()} method.
      * <p>
-     * Here's an example: Lets say that you
+     * Here's an example: Lets say that you have a
-     * have a {@link Vec2f} and to convert it
+     * {@link Vec2f} instance and want to convert
-     * to a String, which you can do with
+     * it to a String. You can do that by using
-     * {@link Vec2f#toString()}. With this flag
+     * {@link Vec2f}'s {@link Vec2f#toString()}
-     * disabled it would return
+     * method. With this flag disabled it will
-     * {@code de.staropensource.engine.base.types.vectors.}{@link Vec2i}{@code (x=64 y=64)},
+     * return
-     * with it however it would just return
+     * {@code de.staropensource.engine.base.types.vectors.}{@link Vec2i}{@code (x=64 y=64)}.
+     * With this flag enabled however the method will return
      * {@link Vec2i}{@code (x=64 y=64)},
      * which is much smaller.
      *
      * @since v1-alpha2
      * -- GETTER --
-     * Gets the value for {@link #hideFullTypePath}.
+     * Returns if to truncate the full path
+     * of a class when invoking using their
+     * {@link #toString()} method.
+     * <p>
+     * Here's an example: Lets say that you have a
+     * {@link Vec2f} instance and want to convert
+     * it to a String. You can do that by using
+     * {@link Vec2f}'s {@link Vec2f#toString()}
+     * method. With this flag disabled it will
+     * return
+     * {@code de.staropensource.engine.base.types.vectors.}{@link Vec2i}{@code (x=64 y=64)}.
+     * With this flag enabled however the method will return
+     * {@link Vec2i}{@code (x=64 y=64)},
+     * which is much smaller.
      *
-     * @return variable value
+     * @return truncate class paths?
-     * @see #hideFullTypePath
      * @since v1-alpha2
      */
     private boolean hideFullTypePath;