+ javadoc

pom.xml

@@ -185,25 +185,13 @@
                 <artifactId>semver-maven-plugin</artifactId>
                 <version>20240116.0.202402</version>
             </plugin>
-            <plugin>
-                <groupId>org.projectlombok</groupId>
-                <artifactId>lombok-maven-plugin</artifactId>
-                <version>1.18.20.0</version>
-                <executions>
-                    <execution>
-                        <phase>generate-sources</phase>
-                        <goals>
-                            <goal>delombok</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>3.6.3</version>
                 <configuration>
                     <sourceFileExcludes>**/_*.java</sourceFileExcludes>
+                    <doclint>all,-missing</doclint>
                 </configuration>
                 <executions>
                     <execution>
@@ -230,12 +218,12 @@
                 <configuration>
                     <java>
                         <palantirJavaFormat>
-                            <version>2.44.0</version>                     <!-- optional -->
+                            <version>2.46.0</version>                     <!-- optional -->
                             <style>PALANTIR</style>                       <!-- or AOSP/GOOGLE (optional) -->
                             <formatJavadoc>true
                             </formatJavadoc>          <!-- defaults to false (optional, requires at least Palantir 2.39.0) -->
                         </palantirJavaFormat>
-                        <removeUnusedImports />
+                        <removeUnusedImports/>
                         <formatAnnotations/>
                     </java>
                 </configuration>

src/main/java/elf4j/engine/NativeLogServiceProvider.java

@@ -44,12 +44,26 @@
 import lombok.NonNull;
 import org.slf4j.MdcAdapterInitializer;
 
-/** */
+/**
+ * The NativeLogServiceProvider class implements the LogServiceProvider and NativeLogServiceManager.Refreshable
+ * interfaces. It is responsible for managing and providing NativeLogger instances for logging purposes. It also
+ * provides methods for refreshing the properties of the log service.
+ *
+ * <p>This class contains a map of native loggers, categorized by their level, and a reference to the class or interface
+ * that the API client calls first to get a logger instance. The client caller class of this class will be the declaring
+ * class of the logger instances this factory produces.
+ *
+ * <p>For this native implementation, the service access class is the {@link Logger} interface itself as the client
+ * calls the static factory method {@link Logger#instance()} first to get a logger instance. If this library is used as
+ * the engine of another logging API, then this access class would be the class in that API that the client calls first
+ * to get a logger instance of that API.
+ */
 public class NativeLogServiceProvider implements LogServiceProvider, NativeLogServiceManager.Refreshable {
     private static final Level DEFAULT_LOGGER_SEVERITY_LEVEL = Level.INFO;
     /** Made injectable for extensions other than this native ELF4J implementation */
     @NonNull private final Level defaultLoggerLevel;
 
+    /** A map of native loggers, categorized by their level. */
     private final Map<Level, Map<String, NativeLogger>> nativeLoggers =
             EnumSet.allOf(Level.class).stream().collect(toMap(Function.identity(), level -> new ConcurrentHashMap<>()));
     /**
@@ -72,12 +86,21 @@ public NativeLogServiceProvider() {
     }
 
     /**
+     * NativeLogServiceProvider constructor with the default logger level and the service access class.
+     *
      * @param serviceAccessClass the class or interface that the API client application calls first to a logger instance
      */
     public NativeLogServiceProvider(@NonNull Class<?> serviceAccessClass) {
         this(DEFAULT_LOGGER_SEVERITY_LEVEL, serviceAccessClass, new ConfiguredNativeLoggerServiceFactory());
     }
 
+    /**
+     * Constructor for the NativeLogServiceProvider class.
+     *
+     * @param defaultLoggerLevel the default logger level
+     * @param serviceAccessClass the class or interface that the API client application calls first to a logger instance
+     * @param nativeLoggerServiceFactory the factory for creating native logger services
+     */
     NativeLogServiceProvider(
             @NonNull Level defaultLoggerLevel,
             @NonNull Class<?> serviceAccessClass,
@@ -101,49 +124,99 @@ public NativeLogger logger() {
                 defaultLoggerLevel, StackTraces.callerOf(serviceAccessClass).getClassName());
     }
 
+    /**
+     * Refreshes the properties of the log service.
+     *
+     * @param properties the new properties for the log service
+     */
     @Override
     public void refresh(@Nullable Properties properties) {
         nativeLoggerServiceFactory.reset(properties);
     }
 
+    /** Reloads the log service. */
     @Override
     public void refresh() {
         nativeLoggerServiceFactory.reload();
     }
 
+    /**
+     * Gets the log service.
+     *
+     * @return the log service
+     */
     @NonNull NativeLoggerService getLogService() {
         return nativeLoggerServiceFactory.getLogService();
     }
 
+    /**
+     * Gets a logger with the specified level and declaring class name.
+     *
+     * @param level the level of the logger
+     * @param declaringClassName the name of the declaring class
+     * @return the logger
+     */
     NativeLogger getLogger(Level level, String declaringClassName) {
         return nativeLoggers.get(level).computeIfAbsent(declaringClassName, k -> new NativeLogger(k, level, this));
     }
 
+    /**
+     * The NativeLoggerServiceFactory interface provides methods for getting the log service, reloading the log service,
+     * and resetting the log service with the specified properties.
+     */
     interface NativeLoggerServiceFactory {
+        /**
+         * Gets the log service.
+         *
+         * @return the log service
+         */
         NativeLoggerService getLogService();
 
+        /** Reloads the log service. */
         void reload();
 
+        /**
+         * Resets the log service with the specified properties.
+         *
+         * @param properties the new properties for the log service
+         */
         void reset(Properties properties);
     }
 
+    /**
+     * The ConfiguredNativeLoggerServiceFactory class implements the NativeLoggerServiceFactory interface and provides a
+     * concrete implementation for getting the log service, reloading the log service, and resetting the log service
+     * with the specified properties.
+     */
     static class ConfiguredNativeLoggerServiceFactory implements NativeLoggerServiceFactory {
         private NativeLoggerService nativeLoggerService;
 
+        /** Constructor for the ConfiguredNativeLoggerServiceFactory class. */
         private ConfiguredNativeLoggerServiceFactory() {
             nativeLoggerService = new EventingNativeLoggerService(LogServiceConfiguration.byLoading());
         }
 
+        /**
+         * Gets the log service.
+         *
+         * @return the log service
+         */
         @Override
         public NativeLoggerService getLogService() {
             return nativeLoggerService;
         }
 
+        /** Reloads the log service. */
         @Override
         public void reload() {
             nativeLoggerService = new EventingNativeLoggerService(LogServiceConfiguration.byLoading());
         }
 
+        /**
+         * Resets the log service with the specified properties.
+         *
+         * @param properties the new properties for the log service
+         */
         @Override
         public void reset(Properties properties) {
             nativeLoggerService = new EventingNativeLoggerService(LogServiceConfiguration.bySetting(properties));

src/main/java/elf4j/engine/service/EventingNativeLoggerService.java

@@ -37,14 +37,22 @@
 import java.util.concurrent.ConcurrentHashMap;
 import lombok.NonNull;
 
-/** converts a log request into an event for async processing */
+/**
+ * The EventingNativeLoggerService class implements the NativeLoggerService interface and is responsible for converting
+ * a log request into an event for async processing. It provides methods for checking if the log should include caller
+ * detail, for checking if a logger is enabled, and for logging a log event.
+ */
 public class EventingNativeLoggerService implements NativeLoggerService {
     private final boolean noop;
     private final LogWriter logWriter;
     private final LoggerOutputLevelThreshold loggerOutputLevelThreshold;
     private final Map<NativeLogger, Boolean> loggerEnabled = new ConcurrentHashMap<>();
 
-    /** @param logServiceConfiguration parsed configuration for the logger service */
+    /**
+     * Constructor for the EventingNativeLoggerService class.
+     *
+     * @param logServiceConfiguration parsed configuration for the logger service
+     */
     public EventingNativeLoggerService(@NonNull LogServiceConfiguration logServiceConfiguration) {
         if (logServiceConfiguration.isAbsent() || logServiceConfiguration.isTrue("noop")) {
             noop = true;
@@ -58,11 +66,22 @@ public EventingNativeLoggerService(@NonNull LogServiceConfiguration logServiceCo
         loggerOutputLevelThreshold = LoggerOutputLevelThreshold.from(logServiceConfiguration);
     }
 
+    /**
+     * Checks if the log should include caller detail such as method, line number, etc.
+     *
+     * @return false as the context element does not include caller detail
+     */
     @Override
     public boolean includeCallerDetail() {
         return logWriter.includeCallerDetail();
     }
 
+    /**
+     * Checks if a logger is enabled.
+     *
+     * @param nativeLogger the logger to check
+     * @return true if the logger is enabled, false otherwise
+     */
     @Override
     public boolean isEnabled(NativeLogger nativeLogger) {
         if (noop) {
@@ -75,6 +94,15 @@ public boolean isEnabled(NativeLogger nativeLogger) {
         });
     }
 
+    /**
+     * Logs a log event.
+     *
+     * @param nativeLogger the logger to use
+     * @param serviceInterfaceClass the class of the service interface
+     * @param throwable the throwable to log
+     * @param message the message to log
+     * @param arguments the arguments to the message
+     */
     @Override
     public void log(
             @NonNull NativeLogger nativeLogger,

src/main/java/elf4j/engine/service/LogEvent.java

@@ -84,17 +84,25 @@ public class LogEvent {
         return o instanceof Supplier<?> ? ((Supplier<?>) o).get() : o;
     }
 
-    /** @return the name of the application client class calling the logging method of this logger instance */
+    /**
+     * Returns the name of the application client class calling the logging method of this logger instance.
+     *
+     * @return the name of the caller class
+     */
     public String getCallerClassName() {
         return callerFrame != null ? callerFrame.getClassName() : nativeLogger.getDeclaringClassName();
     }
 
-    /** @return log message text with all placeholder arguments resolved and replaced by final values */
+    /**
+     * Returns the log message text with all placeholder arguments resolved and replaced by final values.
+     *
+     * @return the resolved log message
+     */
     public CharSequence getResolvedMessage() {
         return resolve(this.message, this.arguments);
     }
 
-    /** */
+    /** Represents a value representing a call stack element. */
     @Value
     @Builder
     public static class StackFrameValue {
@@ -107,6 +115,8 @@ public static class StackFrameValue {
         @Nullable String fileName;
 
         /**
+         * Creates a StackFrameValue instance from a StackTraceElement.
+         *
          * @param stackTraceElement call stack element
          * @return log render-able value representing the call stack element
          */
@@ -120,7 +130,7 @@ public static StackFrameValue from(@NonNull StackTraceElement stackTraceElement)
         }
     }
 
-    /** */
+    /** Represents the value of a thread. */
     @Value
     public static class ThreadValue {
         @NonNull String name;