From 69cf668c4dc2ec85d9f14293b4c5d59ea91db221 Mon Sep 17 00:00:00 2001 From: JeremyStarTM Date: Sun, 10 Nov 2024 17:59:21 +0100 Subject: [PATCH] Heavily improve API doc of EngineConfiguration class --- .../engine/base/EngineConfiguration.java | 280 ++++++++++++------ 1 file changed, 195 insertions(+), 85 deletions(-) diff --git a/base/src/main/java/de/staropensource/engine/base/EngineConfiguration.java b/base/src/main/java/de/staropensource/engine/base/EngineConfiguration.java index 7b800337..afd1ca64 100644 --- a/base/src/main/java/de/staropensource/engine/base/EngineConfiguration.java +++ b/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 - * and excess logging. Unless you want to debug or work - * on a sensitive part of the engine, don't enable this! + * Contains if debugging options should be allowed. + * All debugging options will be forcefully set to + * {@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 - * @see #debug + * @return debugging enabled? * @since v1-alpha0 */ private boolean debug; /** - * If enabled, all called events will be logged. + * Contains whether or not to log + * events being emitted. + *

+ * 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. + *

+ * This will cause all events to + * be logged, with the exception + * of the {@link LogEvent}. * - * @return variable value - * @see #debugEvents + * @return detailed event logging enabled? * @since v1-alpha0 */ private boolean debugEvents; /** - * If enabled, will try to automatically initialize every - * subsystem found though reflection. + * Contains whether or not to automatically discover + * and initialize any class extending {@link SubsystemClass} + * whilst being annotated with {@link EngineSubsystem}. *

- * This however may fail in certain situation, where manual - * subsystem initialization may be required. For this reason, - * this can be turned off before the engine initializes. Please - * note though that dependency resolution between subsystems - * won't be performed, be careful when initializing subsystems manually. + * 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. * * @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}. + *

+ * 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 - * @see #initialPerformSubsystemInitialization + * @return automatically discover and initialize subsystems? * @since v1-alpha5 */ private boolean initialPerformSubsystemInitialization; /** - * Will try to load the specified classes as subsystems, - * if reflective classpath scanning is disabled. + * Contains a set of class names to try to load + * 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 - * @see #initialIncludeSubsystemClasses + * @return set of class names to try and initialize as subsystems * @since v1-alpha5 */ private Set<@NotNull String> initialIncludeSubsystemClasses; /** - * If enabled, will cause {@link ShortcodeParser} to print - * invalid shortcodes as {@link LogLevel#SILENT_WARNING}s. + * Contains whether or not to complain about invalid + * shortcodes. + *

+ * 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. + *

+ * Requires the active log level to be set at least + * to {@link LogLevel#SILENT_WARNING} to have effect. * - * @return variable value - * @see #errorShortcodeParser + * @return complain about invalid shortcodes? + * @see #getLogLevel() * @since v1-alpha0 */ private boolean errorShortcodeParser; /** - * If enabled, will makes the {@link Logger} work asynchronous, - * in a separate platform thread. Don't disable unless you want - * your application to run extremely slowly. + * Contains if to log asynchronously. + *

+ * 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. + *

+ * 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 - * @see #optimizeLogging + * @return log asynchronously? + * @see #getLogPollingSpeed() * @since v1-alpha0 */ private boolean optimizeLogging; /** - * If enabled, will make all events asynchronous, - * in separate virtual threads. Don't disable unless you - * want your application to run slower. + * Contains whether or not to emit events + * asynchronously. + *

+ * This will cause a + * VirtualThread + * 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. + *

+ * This will cause a + * VirtualThread + * to spawn every time an event is emitted. * - * @return variable value - * @see #optimizeEvents + * @return emit events asynchronously? * @since v1-alpha0 */ private boolean optimizeEvents; /** - * Contains which logger levels are allowed - * by setting the minimum logger level. + * Contains the minimum allowed log level. + *

+ * The priority list is as follows (from high to low priority): + *

* - * @see Logger * @since v1-alpha0 * -- GETTER -- - * Gets the value for {@link #logLevel}. + * Returns the minimum allowed log level. + *

+ * The priority list is as follows (from high to low priority): + *

* - * @return variable value - * @see #logLevel + * @return minimum allowed log level * @since v1-alpha0 */ private LogLevel logLevel; @@ -226,75 +293,118 @@ public final class EngineConfiguration extends Configuration { *
  • lineNumber
    • * * - * @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. + *

    + * Available features (in order of appearance): + *

    * - * @return variable value - * @see #logFeatures + * @return optional features to enable * @since v1-alpha8 */ private Set<@NotNull String> logFeatures; /** * Contains how fast the logging thread will - * poll for queued messages. This also causes - * messages to be buffered. + * poll for queued messages in milliseconds. + * This also causes messages to be buffered. *

    * 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. + * 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. * * @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. + *

    + * 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 - * @see #logPollingSpeed + * @return logging thread polling speed in milliseconds + * @see #isOptimizeLogging() * @since v1-alpha4 */ private int logPollingSpeed; /** - * If enabled, will force sos!engine's logging infrastructure to use - * the standard output - * instead of the standard error - * for logging the {@code ERROR} and {@code CRASH} log levels. + * Contains whether or not to forcefully write + * to the standard output instead of the + * standard error stream. + *

    + * This only applies to the {@link LogLevel#ERROR} and + * {@link LogLevel#CRASH} log levels, as these use + * the standard error stream by default. * + * @see man page about standard streams * @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. + *

    + * 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 - * @see #logForceStandardOutput + * @return force use stdout? + * @see man page about standard streams * @since v1-alpha0 */ private boolean logForceStandardOutput; /** - * Will truncate the path of types when using - * their {@code toString} method. + * Contains if to truncate the full path + * of a class when invoking using their + * {@link #toString()} method. *

    - * Here's an example: Lets say that you - * have a {@link Vec2f} and to convert it - * to a String, which you can do with - * {@link Vec2f#toString()}. With this flag - * disabled it would return - * {@code de.staropensource.engine.base.types.vectors.}{@link Vec2i}{@code (x=64 y=64)}, - * with it however it would just return + * 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. * * @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. + *

    + * 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 - * @see #hideFullTypePath + * @return truncate class paths? * @since v1-alpha2 */ private boolean hideFullTypePath;