docs: add JavaDoc with example usage to all main source classes and non-private methods

Agent-Logs-Url: https://github.com/microsphere-projects/microsphere-logging/sessions/e3fe6db3-b002-49d5-9298-701ad373b159

Co-authored-by: mercyblitz <533114+mercyblitz@users.noreply.github.com>

Author: Copilot

microsphere-java-logging/src/main/java/io/microsphere/logging/jdk/JavaLogging.java

@@ -55,41 +55,117 @@ public class JavaLogging implements Logging {
 
     static final LoggingMXBean loggingMXBean = getLoggingMXBean();
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   String rootName = logging.getRootLoggerName();
+     *   // returns "" (empty string for the JDK root logger)
+     * }</pre>
+     */
     @Override
     public String getRootLoggerName() {
         return ROOT_LOGGER_NAME;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   List<String> names = logging.getLoggerNames();
+     * }</pre>
+     */
     @Override
     public List<String> getLoggerNames() {
         return loggingMXBean.getLoggerNames();
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   Set<String> levels = logging.getSupportedLoggingLevels();
+     *   // e.g. ["OFF", "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER", "FINEST", "ALL"]
+     * }</pre>
+     */
     @Override
     public Set<String> getSupportedLoggingLevels() {
         return ALL_LEVELS;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   String level = logging.getLoggerLevel("io.microsphere"); // e.g. "INFO"
+     * }</pre>
+     */
     @Override
     public String getLoggerLevel(String loggerName) {
         return loggingMXBean.getLoggerLevel(loggerName);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   logging.setLoggerLevel("io.microsphere", "FINE");
+     * }</pre>
+     */
     @Override
     public void setLoggerLevel(String loggerName, String levelName) {
         loggingMXBean.setLoggerLevel(loggerName, levelName);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   String parentName = logging.getParentLoggerName("io.microsphere.logging");
+     *   // returns "io.microsphere"
+     * }</pre>
+     */
     @Override
     public String getParentLoggerName(String loggerName) {
         return loggingMXBean.getParentLoggerName(loggerName);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   String name = logging.getName(); // "Java Logging"
+     * }</pre>
+     */
     @Override
     public String getName() {
         return "Java Logging";
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   JavaLogging logging = new JavaLogging();
+     *   int priority = logging.getPriority();
+     *   // returns JavaLogging.PRIORITY
+     * }</pre>
+     */
     @Override
     public int getPriority() {
         return PRIORITY;

microsphere-log4j/src/main/java/io/microsphere/logging/log4j/Log4jLogger.java

@@ -37,87 +37,251 @@ class Log4jLogger extends AbstractLogger implements DelegatingWrapper {
 
     private final Logger logger;
 
+    /**
+     * Creates a new {@link Log4jLogger} for the given logger name.
+     *
+     * @param loggerName the name of the logger
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     * }</pre>
+     */
     public Log4jLogger(String loggerName) {
         super(loggerName);
         this.logger = getLogger(loggerName);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   if (logger.isTraceEnabled()) {
+     *     logger.trace("trace message");
+     *   }
+     * }</pre>
+     */
     @Override
     public boolean isTraceEnabled() {
         return this.logger.isTraceEnabled();
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.trace("entering method foo");
+     * }</pre>
+     */
     @Override
     public void trace(String message) {
         this.logger.trace(message);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.trace("trace with exception", new RuntimeException("cause"));
+     * }</pre>
+     */
     @Override
     public void trace(String message, Throwable t) {
         this.logger.trace(message, t);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   if (logger.isDebugEnabled()) {
+     *     logger.debug("debug message");
+     *   }
+     * }</pre>
+     */
     @Override
     public boolean isDebugEnabled() {
         return this.logger.isDebugEnabled();
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.debug("processing item");
+     * }</pre>
+     */
     @Override
     public void debug(String message) {
         this.logger.debug(message);
 
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.debug("debug with exception", new RuntimeException("cause"));
+     * }</pre>
+     */
     @Override
     public void debug(String message, Throwable t) {
         this.logger.debug(message, t);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   if (logger.isInfoEnabled()) {
+     *     logger.info("application started");
+     *   }
+     * }</pre>
+     */
     @Override
     public boolean isInfoEnabled() {
         return this.logger.isInfoEnabled();
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.info("application started");
+     * }</pre>
+     */
     @Override
     public void info(String message) {
         this.logger.info(message);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.info("info with exception", new RuntimeException("cause"));
+     * }</pre>
+     */
     @Override
     public void info(String message, Throwable t) {
         this.logger.info(message, t);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   if (logger.isWarnEnabled()) {
+     *     logger.warn("low memory");
+     *   }
+     * }</pre>
+     */
     @Override
     public boolean isWarnEnabled() {
         return this.logger.isEnabledFor(WARN);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.warn("unexpected configuration value");
+     * }</pre>
+     */
     @Override
     public void warn(String message) {
         this.logger.warn(message);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.warn("warn with exception", new RuntimeException("cause"));
+     * }</pre>
+     */
     @Override
     public void warn(String message, Throwable t) {
         this.logger.warn(message, t);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   if (logger.isErrorEnabled()) {
+     *     logger.error("operation failed");
+     *   }
+     * }</pre>
+     */
     @Override
     public boolean isErrorEnabled() {
         return this.logger.isEnabledFor(ERROR);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.error("operation failed");
+     * }</pre>
+     */
     @Override
     public void error(String message) {
         this.logger.error(message);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   logger.error("error with exception", new RuntimeException("cause"));
+     * }</pre>
+     */
     @Override
     public void error(String message, Throwable t) {
         this.logger.error(message, t);
     }
 
+    /**
+     * Returns the underlying Log4j {@link Logger} delegate.
+     *
+     * <h3>Example Usage</h3>
+     * <pre>{@code
+     *   Log4jLogger logger = new Log4jLogger("io.microsphere");
+     *   org.apache.log4j.Logger delegate = (org.apache.log4j.Logger) logger.getDelegate();
+     * }</pre>
+     */
     @Override
     public Object getDelegate() {
         return this.logger;