Reposition Example Usage sections above @param/@return in JavaDoc

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

@@ -40,12 +40,12 @@ class Log4jLogger extends AbstractLogger implements DelegatingWrapper {
     /**
      * 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>
+     * @param loggerName the name of the logger
+     *
      */
     public Log4jLogger(String loggerName) {
         super(loggerName);

microsphere-log4j2/src/main/java/io/microsphere/logging/log4j2/Log4j2Logger.java

@@ -38,12 +38,12 @@ class Log4j2Logger extends AbstractLogger implements DelegatingWrapper {
     /**
      * Creates a new {@link Log4j2Logger} for the given logger name.
      *
-     * @param loggerName the name of the logger
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   Log4j2Logger logger = new Log4j2Logger("io.microsphere");
      * }</pre>
+     * @param loggerName the name of the logger
+     *
      */
     public Log4j2Logger(String loggerName) {
         super(loggerName);

microsphere-log4j2/src/main/java/io/microsphere/logging/log4j2/LogEventComparator.java

@@ -42,17 +42,17 @@ private LogEventComparator() {
      * Returns a negative integer, zero, or a positive integer if the first event's time
      * is earlier than, equal to, or later than the second.
      *
-     * @param o1 the first {@link LogEvent}
-     * @param o2 the second {@link LogEvent}
-     * @return a negative integer, zero, or positive integer
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   LogEvent event1 = ...; // earlier event
      *   LogEvent event2 = ...; // later event
      *   int result = LogEventComparator.INSTANCE.compare(event1, event2);
      *   // result < 0 means event1 occurred before event2
      * }</pre>
+     * @param o1 the first {@link LogEvent}
+     * @param o2 the second {@link LogEvent}
+     * @return a negative integer, zero, or positive integer
+     *
      */
     @Override
     public int compare(LogEvent o1, LogEvent o2) {

microsphere-log4j2/src/main/java/io/microsphere/logging/log4j2/appender/InMemoryAppender.java

@@ -47,8 +47,6 @@ public class InMemoryAppender extends AbstractLifeCycle implements Appender {
     /**
      * Appends the given {@link LogEvent} to the in-memory collection.
      *
-     * @param event the {@link LogEvent} to record
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
@@ -60,6 +58,8 @@ public class InMemoryAppender extends AbstractLifeCycle implements Appender {
      *       .build();
      *   appender.append(event);
      * }</pre>
+     * @param event the {@link LogEvent} to record
+     *
      */
     @Override
     public void append(LogEvent event) {
@@ -69,13 +69,13 @@ public void append(LogEvent event) {
     /**
      * Returns the name of this appender, which is {@value #NAME}.
      *
-     * @return the constant name {@value #NAME}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   String name = appender.getName(); // "InMemory"
      * }</pre>
+     * @return the constant name {@value #NAME}
+     *
      */
     @Override
     public String getName() {
@@ -85,13 +85,13 @@ public String getName() {
     /**
      * Returns {@code null} because this appender does not use a {@link Layout}.
      *
-     * @return always {@code null}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   Layout<?> layout = appender.getLayout(); // null
      * }</pre>
+     * @return always {@code null}
+     *
      */
     @Override
     public Layout<? extends Serializable> getLayout() {
@@ -101,13 +101,13 @@ public Layout<? extends Serializable> getLayout() {
     /**
      * Returns {@code false} because this appender does not silently ignore exceptions.
      *
-     * @return always {@code false}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   boolean ignore = appender.ignoreExceptions(); // false
      * }</pre>
+     * @return always {@code false}
+     *
      */
     @Override
     public boolean ignoreExceptions() {
@@ -117,13 +117,13 @@ public boolean ignoreExceptions() {
     /**
      * Returns {@code null} because this appender does not use an {@link ErrorHandler}.
      *
-     * @return always {@code null}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   ErrorHandler handler = appender.getHandler(); // null
      * }</pre>
+     * @return always {@code null}
+     *
      */
     @Override
     public ErrorHandler getHandler() {
@@ -133,13 +133,13 @@ public ErrorHandler getHandler() {
     /**
      * No-op: this appender does not support setting an {@link ErrorHandler}.
      *
-     * @param handler ignored
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   appender.setHandler(null); // no-op
      * }</pre>
+     * @param handler ignored
+     *
      */
     @Override
     public void setHandler(ErrorHandler handler) {
@@ -194,8 +194,6 @@ public void stop() {
     /**
      * Transfer all log events to another {@link Appender}
      *
-     * @param appender another {@link Appender}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender source = new InMemoryAppender();
@@ -204,6 +202,8 @@ public void stop() {
      *   FileAppender target = ...;
      *   source.transfer(target);
      * }</pre>
+     * @param appender another {@link Appender}
+     *
      */
     public void transfer(Appender appender) {
         LogEvent logEvent;
@@ -216,15 +216,15 @@ public void transfer(Appender appender) {
      * Finds and returns the {@link InMemoryAppender} registered in the current Log4j2 configuration,
      * or {@code null} if none is registered.
      *
-     * @return the registered {@link InMemoryAppender}, or {@code null} if not found
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = InMemoryAppender.findInMemoryAppender();
      *   if (appender != null) {
      *     appender.transfer(anotherAppender);
      *   }
      * }</pre>
+     * @return the registered {@link InMemoryAppender}, or {@code null} if not found
+     *
      */
     public static InMemoryAppender findInMemoryAppender() {
         return findAppender(NAME);

microsphere-log4j2/src/main/java/io/microsphere/logging/log4j2/layout/DelegatingLayout.java

@@ -37,13 +37,13 @@ public class DelegatingLayout<T extends Serializable> implements Layout<T> {
     /**
      * Creates a new {@link DelegatingLayout} wrapping the given delegate {@link Layout}.
      *
-     * @param delegate the {@link Layout} to delegate to
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   Layout<String> patternLayout = PatternLayout.newBuilder().withPattern("%m").build();
      *   DelegatingLayout<String> layout = new DelegatingLayout<>(patternLayout);
      * }</pre>
+     * @param delegate the {@link Layout} to delegate to
+     *
      */
     public DelegatingLayout(Layout<T> delegate) {
         this.delegate = delegate;
@@ -163,13 +163,13 @@ public void encode(LogEvent source, ByteBufferDestination destination) {
     /**
      * Returns the underlying delegate {@link Layout}.
      *
-     * @return the delegate {@link Layout}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   DelegatingLayout<String> layout = new DelegatingLayout<>(patternLayout);
      *   Layout<String> delegate = layout.getDelegate();
      * }</pre>
+     * @return the delegate {@link Layout}
+     *
      */
     public Layout<T> getDelegate() {
         return delegate;
@@ -178,13 +178,13 @@ public Layout<T> getDelegate() {
     /**
      * Sets a new delegate {@link Layout}.
      *
-     * @param delegate the new delegate {@link Layout}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   DelegatingLayout<String> layout = new DelegatingLayout<>();
      *   layout.setDelegate(PatternLayout.newBuilder().withPattern("%d %m").build());
      * }</pre>
+     * @param delegate the new delegate {@link Layout}
+     *
      */
     public void setDelegate(Layout<T> delegate) {
         this.delegate = delegate;

microsphere-log4j2/src/main/java/io/microsphere/logging/log4j2/layout/SmartFileAppenderLayout.java

@@ -53,13 +53,13 @@ public class SmartFileAppenderLayout<T extends Serializable> implements Layout<T
      * Creates a new {@link SmartFileAppenderLayout} that inspects the given {@link LoggerContext}
      * to select the appropriate delegating {@link Layout} per logger name.
      *
-     * @param context the {@link LoggerContext} used to discover file appenders
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   LoggerContext context = (LoggerContext) LogManager.getContext(false);
      *   SmartFileAppenderLayout<?> layout = new SmartFileAppenderLayout<>(context);
      * }</pre>
+     * @param context the {@link LoggerContext} used to discover file appenders
+     *
      */
     public SmartFileAppenderLayout(LoggerContext context) {
         this.delegatingLayouts = initDelegatingLayouts(context);

microsphere-log4j2/src/main/java/io/microsphere/logging/log4j2/util/Log4j2Utils.java

@@ -192,12 +192,12 @@ public static Collection<Logger> getLoggers() {
     /**
      * Apply the given {@link Consumer} to each {@link Logger} in the current {@link LoggerContext}.
      *
-     * @param loggerConsumer the consumer to apply
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   Log4j2Utils.doInLogger(logger -> logger.setLevel(Level.DEBUG));
      * }</pre>
+     * @param loggerConsumer the consumer to apply
+     *
      */
     public static void doInLogger(Consumer<Logger> loggerConsumer) {
         getLoggers().forEach(loggerConsumer);
@@ -206,15 +206,15 @@ public static void doInLogger(Consumer<Logger> loggerConsumer) {
     /**
      * Add the given {@link Appender} to the specified {@link Logger} instances.
      *
-     * @param appender the {@link Appender} to add
-     * @param loggers  the {@link Logger} instances to which the appender is added
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   Collection<Logger> loggers = Log4j2Utils.getLoggers();
      *   Log4j2Utils.addAppender(appender, loggers);
      * }</pre>
+     * @param appender the {@link Appender} to add
+     * @param loggers  the {@link Logger} instances to which the appender is added
+     *
      */
     public static void addAppender(Appender appender, Iterable<Logger> loggers) {
         LoggerContext loggerContext = getLoggerContext();
@@ -224,13 +224,13 @@ public static void addAppender(Appender appender, Iterable<Logger> loggers) {
     /**
      * Add the given {@link Appender} to all {@link Logger} instances in the current {@link LoggerContext}.
      *
-     * @param appender the {@link Appender} to add to all loggers
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   Log4j2Utils.addAppenderForAllLoggers(appender);
      * }</pre>
+     * @param appender the {@link Appender} to add to all loggers
+     *
      */
     public static void addAppenderForAllLoggers(Appender appender) {
         LoggerContext loggerContext = getLoggerContext();
@@ -240,15 +240,15 @@ public static void addAppenderForAllLoggers(Appender appender) {
     /**
      * Remove the given {@link Appender} from the specified {@link Logger} instances.
      *
-     * @param appender the {@link Appender} to remove
-     * @param loggers  the {@link Logger} instances from which the appender is removed
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = new InMemoryAppender();
      *   Collection<Logger> loggers = Log4j2Utils.getLoggers();
      *   Log4j2Utils.removeAppender(appender, loggers);
      * }</pre>
+     * @param appender the {@link Appender} to remove
+     * @param loggers  the {@link Logger} instances from which the appender is removed
+     *
      */
     public static void removeAppender(Appender appender, Iterable<Logger> loggers) {
         LoggerContext loggerContext = getLoggerContext();
@@ -258,13 +258,13 @@ public static void removeAppender(Appender appender, Iterable<Logger> loggers) {
     /**
      * Remove the given {@link Appender} from all {@link Logger} instances in the current {@link LoggerContext}.
      *
-     * @param appender the {@link Appender} to remove from all loggers
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   InMemoryAppender appender = Log4j2Utils.findAppender(InMemoryAppender.NAME);
      *   Log4j2Utils.removeAppenderForAllLoggers(appender);
      * }</pre>
+     * @param appender the {@link Appender} to remove from all loggers
+     *
      */
     public static void removeAppenderForAllLoggers(Appender appender) {
         LoggerContext loggerContext = getLoggerContext();

microsphere-logging-commons/src/main/java/io/microsphere/logging/jmx/LoggingMXBeanAdapter.java

@@ -38,13 +38,13 @@ public class LoggingMXBeanAdapter implements LoggingMXBean, DelegatingWrapper {
     /**
      * Creates a new {@link LoggingMXBeanAdapter} wrapping the given {@link Logging} instance.
      *
-     * @param logging the {@link Logging} delegate; must not be {@code null}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   Logging logging = LoggingUtils.load();
      *   LoggingMXBeanAdapter adapter = new LoggingMXBeanAdapter(logging);
      * }</pre>
+     * @param logging the {@link Logging} delegate; must not be {@code null}
+     *
      */
     public LoggingMXBeanAdapter(Logging logging) {
         this.logging = logging;

microsphere-logging-test/src/main/java/io/microsphere/logging/test/junit4/LoggingLevelsRule.java

@@ -57,14 +57,14 @@ public Statement apply(Statement base, Description description) {
     /**
      * Creates a new {@link LoggingLevelsRule} for the given logging levels.
      *
-     * @param levels the logging levels to iterate through (e.g. "TRACE", "DEBUG", "INFO")
-     * @return a new {@link LoggingLevelsRule}
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   @ClassRule
      *   public static final LoggingLevelsRule loggingLevelsRule = LoggingLevelsRule.levels("TRACE", "DEBUG", "INFO");
      * }</pre>
+     * @param levels the logging levels to iterate through (e.g. "TRACE", "DEBUG", "INFO")
+     * @return a new {@link LoggingLevelsRule}
+     *
      */
     public static LoggingLevelsRule levels(String... levels) {
         return new LoggingLevelsRule(levels);

microsphere-logging-test/src/main/java/io/microsphere/logging/test/junit4/LoggingLevelsStatement.java

@@ -49,14 +49,14 @@ public class LoggingLevelsStatement extends Statement {
     /**
      * Creates a new {@link LoggingLevelsStatement} with the specified statement, description, and logging levels.
      *
-     * @param next        the original JUnit {@link Statement} to wrap
-     * @param description the test {@link Description}
-     * @param levels      the logging level names to iterate
-     *
      * <h3>Example Usage</h3>
      * <pre>{@code
      *   LoggingLevelsStatement statement = new LoggingLevelsStatement(base, description, "TRACE", "DEBUG", "INFO");
      * }</pre>
+     * @param next        the original JUnit {@link Statement} to wrap
+     * @param description the test {@link Description}
+     * @param levels      the logging level names to iterate
+     *
      */
     protected LoggingLevelsStatement(Statement next, Description description, String... levels) {
         this.next = next;