improve javadocs

Signed-off-by: Ceki Gulcu <ceki@qos.ch>

parent/pom.xml

@@ -48,7 +48,7 @@
     <maven-source-plugin.version>3.2.1</maven-source-plugin.version>
     <maven-deploy-plugin.version>3.0.0-M1</maven-deploy-plugin.version>
     <maven-jar-plugin.version>3.2.0</maven-jar-plugin.version>
-    <maven-jxr-plugin.version>3.1.1</maven-jxr-plugin.version>
+    <maven-jxr-plugin.version>3.3.1</maven-jxr-plugin.version>
     <maven-bundle-plugin.version>5.1.9</maven-bundle-plugin.version>
   </properties>
 
@@ -139,7 +139,7 @@
             <linksource>true</linksource>
             <additionalOptions>
               <additionalOption>-Xdoclint:none</additionalOption>
-              <additionalOption>doclint:none</additionalOption>
+              <!--              <additionalOption>doclint:none</additionalOption>-->
             </additionalOptions>
           </configuration>
         </plugin>
@@ -257,23 +257,23 @@
         <version>${maven-site-plugin.version}</version>
       </plugin>
 
-<!--      <plugin>-->
-<!--        <groupId>org.apache.maven.plugins</groupId>-->
-<!--        <artifactId>maven-javadoc-plugin</artifactId>-->
-<!--        <configuration>-->
-<!--          <skippedModules>-->
-<!--            :slf4j-ext,:log4j-over-slf4j,:log4j-over-slf4j-blackbox,jul-to-slf4j-blackbox,slf4j-migrator,:osgi-over-slf4j-->
-<!--          </skippedModules>-->
-<!--        </configuration>-->
-<!--      </plugin>-->
+      <!--      <plugin>-->
+      <!--        <groupId>org.apache.maven.plugins</groupId>-->
+      <!--        <artifactId>maven-javadoc-plugin</artifactId>-->
+      <!--        <configuration>-->
+      <!--          <skippedModules>-->
+      <!--            :slf4j-ext,:log4j-over-slf4j,:log4j-over-slf4j-blackbox,jul-to-slf4j-blackbox,slf4j-migrator,:osgi-over-slf4j-->
+      <!--          </skippedModules>-->
+      <!--        </configuration>-->
+      <!--      </plugin>-->
 
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-jxr-plugin</artifactId>
         <version>${maven-jxr-plugin.version}</version>
         <configuration>
           <aggregate>true</aggregate>
-          <javadocDir>target/site/apidocs/</javadocDir>
+          <javadocDir>target/site/apidocs2/</javadocDir>
           <linkJavadoc>true</linkJavadoc>
         </configuration>
       </plugin>
@@ -282,7 +282,37 @@
   </build>
 
   <reporting>
-   </reporting>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-javadoc-plugin</artifactId>
+        <version>${maven-javadoc-plugin.version}</version>
+        <configuration>
+          <verbose>true</verbose>
+          <skippedModules>
+            slf4j-ext,log4j-over-slf4j,log4j-over-slf4j-blackbox,jul-to-slf4j-blackbox,slf4j-migrator,osgi-over-slf4j
+          </skippedModules>
+          <detectLinks>true</detectLinks>
+          <linksource>true</linksource>
+          <additionalOptions>
+            <additionalOption>-Xdoclint:none</additionalOption>
+            <!--              <additionalOption>doclint:none</additionalOption>-->
+          </additionalOptions>
+        </configuration>
+      </plugin>
+
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-jxr-plugin</artifactId>
+        <version>${maven-jxr-plugin.version}</version>
+        <configuration>
+          <javadocDir>target/site/apidocs/</javadocDir>
+          <linkJavadoc>true</linkJavadoc>
+        </configuration>
+      </plugin>
+
+    </plugins>
+  </reporting>
 
   <profiles>
     <profile>

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'

slf4j-api/src/main/java/module-info.java

@@ -1,8 +1,20 @@
-module org.slf4j { 
+/**
+ *  <p>This module defines the SLF4J API. </p>
+ *
+ *  <p>More specifically, the {@link org.slf4j} package contains client-facing classes and interfaces.</p>
+ *
+ *  <p>The {@link org.slf4j.spi} package contains classes which are intended for logging backends. In particular, </p>
+ *  ogging back-ends must provide a {@link org.slf4j.spi.SLF4JServiceProvider} implementation in order to be picked
+ *  up by SLF4J at initialization time.
+ *  </p>
+ *
+ * @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;
 }

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;

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;

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
  */

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;

slf4j-api/src/main/java/org/slf4j/event/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * SLF4J internal representation of a logging event.
+ *
+ *  <p>>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.
+ * </p>
+ */
+package org.slf4j.event;

slf4j-api/src/main/java/org/slf4j/helpers/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * Various SLF4J <b>internal</b> utility and helper classes.
+ *
+ */
+package org.slf4j.helpers;

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;

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.
+ *
+ * <p>
+ * 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.
+ * </p>
+ *
+ */
+package org.slf4j.spi;