From e3205a47ce16ce43d49ecabcc51f80102ddddd76 Mon Sep 17 00:00:00 2001 From: Ceki Gulcu Date: Thu, 21 Dec 2023 19:58:46 +0100 Subject: [PATCH] improve javadocs Signed-off-by: Ceki Gulcu --- parent/pom.xml | 56 +++++++++++++----- release.sh | 2 + slf4j-api/src/main/java/module-info.java | 16 ++++- .../java/org/slf4j/event/EventConstants.java | 5 ++ .../java/org/slf4j/event/KeyValuePair.java | 6 ++ .../src/main/java/org/slf4j/event/Level.java | 5 +- .../slf4j/event/SubstituteLoggingEvent.java | 7 +++ .../java/org/slf4j/event/package-info.java | 8 +++ .../java/org/slf4j/helpers/package-info.java | 5 ++ .../main/java/org/slf4j/helpers/package.html | 16 ----- .../src/main/java/org/slf4j/package-info.java | 6 ++ .../src/main/java/org/slf4j/package.html | 16 ----- .../org/slf4j/spi/LoggerFactoryBinder.java | 58 ------------------- .../org/slf4j/spi/MarkerFactoryBinder.java | 58 ------------------- .../main/java/org/slf4j/spi/package-info.java | 10 ++++ .../src/main/java/org/slf4j/spi/package.html | 8 --- 16 files changed, 108 insertions(+), 174 deletions(-) create mode 100644 slf4j-api/src/main/java/org/slf4j/event/package-info.java create mode 100644 slf4j-api/src/main/java/org/slf4j/helpers/package-info.java delete mode 100644 slf4j-api/src/main/java/org/slf4j/helpers/package.html create mode 100644 slf4j-api/src/main/java/org/slf4j/package-info.java delete mode 100644 slf4j-api/src/main/java/org/slf4j/package.html delete mode 100644 slf4j-api/src/main/java/org/slf4j/spi/LoggerFactoryBinder.java delete mode 100644 slf4j-api/src/main/java/org/slf4j/spi/MarkerFactoryBinder.java create mode 100644 slf4j-api/src/main/java/org/slf4j/spi/package-info.java delete mode 100644 slf4j-api/src/main/java/org/slf4j/spi/package.html diff --git a/parent/pom.xml b/parent/pom.xml index 0f78f1426..16bed26c5 100644 --- a/parent/pom.xml +++ b/parent/pom.xml @@ -48,7 +48,7 @@ 3.2.1 3.0.0-M1 3.2.0 - 3.1.1 + 3.3.1 5.1.9 @@ -139,7 +139,7 @@ true -Xdoclint:none - doclint:none + @@ -257,15 +257,15 @@ ${maven-site-plugin.version} - - - - - - - - - + + + + + + + + + org.apache.maven.plugins @@ -273,7 +273,7 @@ ${maven-jxr-plugin.version} true - target/site/apidocs/ + target/site/apidocs2/ true @@ -282,7 +282,37 @@ - + + + org.apache.maven.plugins + maven-javadoc-plugin + ${maven-javadoc-plugin.version} + + true + + slf4j-ext,log4j-over-slf4j,log4j-over-slf4j-blackbox,jul-to-slf4j-blackbox,slf4j-migrator,osgi-over-slf4j + + true + true + + -Xdoclint:none + + + + + + + org.apache.maven.plugins + maven-jxr-plugin + ${maven-jxr-plugin.version} + + target/site/apidocs/ + true + + + + + diff --git a/release.sh b/release.sh index e72263850..2473ae1e4 100755 --- a/release.sh +++ b/release.sh @@ -5,6 +5,8 @@ #rscpSLF4J apidocs/ # mvn -Ddoclint=none -Dmaven.javadoc.skippedModules=slf4j-ext,log4j-over-slf4j,log4j-over-slf4j-blackbox,jul-to-slf4j-blackbox,slf4j-migrator,osgi-over-slf4j javadoc:aggregate + +#mvn -Ddoclint=none -DXXadditionalparam=-Xdoclint:none -Dmaven.javadoc.skippedModules=osgi-over-slf4j,slf4j-ext,log4j-over-slf4j-blackbox,log4j-over-slf4j javadoc:aggregate #mvn versions:set -DgenerateBackupPoms=false -DnewVersion=${VERSION_NUMBER} MVN='/java/maven-3.5.2//bin/mvn' diff --git a/slf4j-api/src/main/java/module-info.java b/slf4j-api/src/main/java/module-info.java index 96f08f29e..f2078aa66 100644 --- a/slf4j-api/src/main/java/module-info.java +++ b/slf4j-api/src/main/java/module-info.java @@ -1,8 +1,20 @@ -module org.slf4j { +/** + *

This module defines the SLF4J API.

+ * + *

More specifically, the {@link org.slf4j} package contains client-facing classes and interfaces.

+ * + *

The {@link org.slf4j.spi} package contains classes which are intended for logging backends. In particular,

+ * ogging back-ends must provide a {@link org.slf4j.spi.SLF4JServiceProvider} implementation in order to be picked + * up by SLF4J at initialization time. + *

+ * + * @moduleGraph + */ +module org.slf4j { exports org.slf4j; exports org.slf4j.spi; exports org.slf4j.event; exports org.slf4j.helpers; uses org.slf4j.spi.SLF4JServiceProvider; -requires java.base; + requires java.base; } diff --git a/slf4j-api/src/main/java/org/slf4j/event/EventConstants.java b/slf4j-api/src/main/java/org/slf4j/event/EventConstants.java index 00975da27..c91343b48 100755 --- a/slf4j-api/src/main/java/org/slf4j/event/EventConstants.java +++ b/slf4j-api/src/main/java/org/slf4j/event/EventConstants.java @@ -2,6 +2,11 @@ import org.slf4j.spi.LocationAwareLogger; +/** + * Various constants used by {@link Level} and {@link org.slf4j.Logger}. + * + * + */ public class EventConstants { public static final int ERROR_INT = LocationAwareLogger.ERROR_INT; public static final int WARN_INT = LocationAwareLogger.WARN_INT; diff --git a/slf4j-api/src/main/java/org/slf4j/event/KeyValuePair.java b/slf4j-api/src/main/java/org/slf4j/event/KeyValuePair.java index 9aebe1985..194f15240 100755 --- a/slf4j-api/src/main/java/org/slf4j/event/KeyValuePair.java +++ b/slf4j-api/src/main/java/org/slf4j/event/KeyValuePair.java @@ -2,6 +2,12 @@ import java.util.Objects; +/** + * Instances of this class store the key value pair passed to a {@link org.slf4j.Logger logger} via + * the {@link org.slf4j.spi.LoggingEventBuilder#addKeyValue(String, Object)} method of the fluent API. + * + * @since 2.0.0 + */ public class KeyValuePair { public final String key; diff --git a/slf4j-api/src/main/java/org/slf4j/event/Level.java b/slf4j-api/src/main/java/org/slf4j/event/Level.java index a288b06b2..e026f912f 100755 --- a/slf4j-api/src/main/java/org/slf4j/event/Level.java +++ b/slf4j-api/src/main/java/org/slf4j/event/Level.java @@ -7,9 +7,8 @@ import static org.slf4j.event.EventConstants.WARN_INT; /** - * SLF4J's internal representation of Level. - * - * + * SLF4J's internal representation of a level. + * * @author Ceki Gülcü * @since 1.7.15 */ diff --git a/slf4j-api/src/main/java/org/slf4j/event/SubstituteLoggingEvent.java b/slf4j-api/src/main/java/org/slf4j/event/SubstituteLoggingEvent.java index 4c8f7ad7f..30c3a9ce7 100755 --- a/slf4j-api/src/main/java/org/slf4j/event/SubstituteLoggingEvent.java +++ b/slf4j-api/src/main/java/org/slf4j/event/SubstituteLoggingEvent.java @@ -7,6 +7,13 @@ import org.slf4j.Marker; import org.slf4j.helpers.SubstituteLogger; +/** + * An implementation of {@link LoggingEvent} used to store logging events generated during logging backend + * initialization. + * + * @author Ceki Gülcü + * @since 1.7.15 + */ public class SubstituteLoggingEvent implements LoggingEvent { Level level; diff --git a/slf4j-api/src/main/java/org/slf4j/event/package-info.java b/slf4j-api/src/main/java/org/slf4j/event/package-info.java new file mode 100644 index 000000000..bb16e2064 --- /dev/null +++ b/slf4j-api/src/main/java/org/slf4j/event/package-info.java @@ -0,0 +1,8 @@ +/** + * SLF4J internal representation of a logging event. + * + *

>Most notably, the {@link org.slf4j.event.LoggingEvent} interface, a minimal interface sufficient for + * the restitution of data passed by the user to the SLF4J API. + *

+ */ +package org.slf4j.event; \ No newline at end of file diff --git a/slf4j-api/src/main/java/org/slf4j/helpers/package-info.java b/slf4j-api/src/main/java/org/slf4j/helpers/package-info.java new file mode 100644 index 000000000..b141980fb --- /dev/null +++ b/slf4j-api/src/main/java/org/slf4j/helpers/package-info.java @@ -0,0 +1,5 @@ +/** + * Various SLF4J internal utility and helper classes. + * + */ +package org.slf4j.helpers; \ No newline at end of file diff --git a/slf4j-api/src/main/java/org/slf4j/helpers/package.html b/slf4j-api/src/main/java/org/slf4j/helpers/package.html deleted file mode 100644 index f223543d4..000000000 --- a/slf4j-api/src/main/java/org/slf4j/helpers/package.html +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - - - -

Helper classes.

- -
- - diff --git a/slf4j-api/src/main/java/org/slf4j/package-info.java b/slf4j-api/src/main/java/org/slf4j/package-info.java new file mode 100644 index 000000000..3833b7388 --- /dev/null +++ b/slf4j-api/src/main/java/org/slf4j/package-info.java @@ -0,0 +1,6 @@ +/** + * Core logging interfaces. + * + * This packages contains the "core", that is client facing, classes and interfaces of the SLF4J API. + */ +package org.slf4j; \ No newline at end of file diff --git a/slf4j-api/src/main/java/org/slf4j/package.html b/slf4j-api/src/main/java/org/slf4j/package.html deleted file mode 100644 index 323bac218..000000000 --- a/slf4j-api/src/main/java/org/slf4j/package.html +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - - - -

Core logging interfaces.

- -
- - diff --git a/slf4j-api/src/main/java/org/slf4j/spi/LoggerFactoryBinder.java b/slf4j-api/src/main/java/org/slf4j/spi/LoggerFactoryBinder.java deleted file mode 100644 index 169691f35..000000000 --- a/slf4j-api/src/main/java/org/slf4j/spi/LoggerFactoryBinder.java +++ /dev/null @@ -1,58 +0,0 @@ -/** - * Copyright (c) 2004-2011 QOS.ch - * All rights reserved. - * - * Permission is hereby granted, free of charge, to any person obtaining - * a copy of this software and associated documentation files (the - * "Software"), to deal in the Software without restriction, including - * without limitation the rights to use, copy, modify, merge, publish, - * distribute, sublicense, and/or sell copies of the Software, and to - * permit persons to whom the Software is furnished to do so, subject to - * the following conditions: - * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE - * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION - * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION - * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * - */ -package org.slf4j.spi; - -import org.slf4j.ILoggerFactory; - -/** - * An internal interface which helps the static {@link org.slf4j.LoggerFactory} - * class bind with the appropriate {@link ILoggerFactory} instance. - * - * @author Ceki Gülcü - * @deprecated - */ -public interface LoggerFactoryBinder { - - /** - * Return the instance of {@link ILoggerFactory} that - * {@link org.slf4j.LoggerFactory} class should bind to. - * - * @return the instance of {@link ILoggerFactory} that - * {@link org.slf4j.LoggerFactory} class should bind to. - */ - public ILoggerFactory getLoggerFactory(); - - /** - * The String form of the {@link ILoggerFactory} object that this - * LoggerFactoryBinder instance is intended to return. - * - *

This method allows the developer to interrogate this binder's intention - * which may be different from the {@link ILoggerFactory} instance it is able to - * yield in practice. The discrepancy should only occur in case of errors. - * - * @return the class name of the intended {@link ILoggerFactory} instance - */ - public String getLoggerFactoryClassStr(); -} diff --git a/slf4j-api/src/main/java/org/slf4j/spi/MarkerFactoryBinder.java b/slf4j-api/src/main/java/org/slf4j/spi/MarkerFactoryBinder.java deleted file mode 100644 index 0502ffad2..000000000 --- a/slf4j-api/src/main/java/org/slf4j/spi/MarkerFactoryBinder.java +++ /dev/null @@ -1,58 +0,0 @@ -/** - * Copyright (c) 2004-2011 QOS.ch - * All rights reserved. - * - * Permission is hereby granted, free of charge, to any person obtaining - * a copy of this software and associated documentation files (the - * "Software"), to deal in the Software without restriction, including - * without limitation the rights to use, copy, modify, merge, publish, - * distribute, sublicense, and/or sell copies of the Software, and to - * permit persons to whom the Software is furnished to do so, subject to - * the following conditions: - * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF - * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE - * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION - * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION - * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - * - */ -package org.slf4j.spi; - -import org.slf4j.IMarkerFactory; - -/** - * An internal interface which helps the static {@link org.slf4j.MarkerFactory} - * class bind with the appropriate {@link IMarkerFactory} instance. - * - * @author Ceki Gülcü - * @deprecated - */ -public interface MarkerFactoryBinder { - - /** - * Return the instance of {@link IMarkerFactory} that - * {@link org.slf4j.MarkerFactory} class should bind to. - * - * @return the instance of {@link IMarkerFactory} that - * {@link org.slf4j.MarkerFactory} class should bind to. - */ - public IMarkerFactory getMarkerFactory(); - - /** - * The String form of the {@link IMarkerFactory} object that this - * MarkerFactoryBinder instance is intended to return. - * - *

This method allows the developer to interrogate this binder's intention - * which may be different from the {@link IMarkerFactory} instance it is able to - * return. Such a discrepancy should only occur in case of errors. - * - * @return the class name of the intended {@link IMarkerFactory} instance - */ - public String getMarkerFactoryClassStr(); -} diff --git a/slf4j-api/src/main/java/org/slf4j/spi/package-info.java b/slf4j-api/src/main/java/org/slf4j/spi/package-info.java new file mode 100644 index 000000000..1e403a915 --- /dev/null +++ b/slf4j-api/src/main/java/org/slf4j/spi/package-info.java @@ -0,0 +1,10 @@ +/** + * Contains classes and interfaces which are intended for logging backends. + * + *

+ * Logging back-ends wishing to interact with SLF4J must provide a {@link org.slf4j.spi.SLF4JServiceProvider} + * implementation in order to be picked up by SLF4J at initialization time. + *

+ * + */ +package org.slf4j.spi; \ No newline at end of file diff --git a/slf4j-api/src/main/java/org/slf4j/spi/package.html b/slf4j-api/src/main/java/org/slf4j/spi/package.html deleted file mode 100644 index 13ea8923a..000000000 --- a/slf4j-api/src/main/java/org/slf4j/spi/package.html +++ /dev/null @@ -1,8 +0,0 @@ - - - - -Classes and interfaces which are internal to SLF4J. Under most -circumstances SLF4J users should be oblivious even to the existence of -this package. - \ No newline at end of file