polish the docs on slf4j.detectLoggerNameMismatch

pom.xml

@@ -40,6 +40,7 @@
     <log4j.version>1.2.17</log4j.version>
     <logback.version>1.0.13</logback.version>
     <junit.version>4.10</junit.version>
+    <maven-site-plugin.version>3.3</maven-site-plugin.version>
   </properties>
 
   <developers>
@@ -142,8 +143,7 @@
         <artifactId>maven-jar-plugin</artifactId>
         <version>2.3.1</version>
       </plugin>
-
+ 
-
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-plugin</artifactId>
@@ -206,7 +206,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-site-plugin</artifactId>
-        <version>3.0</version>
+        <version>${maven-site-plugin.version}</version>
         <configuration>
           <reportPlugins>
             <plugin>
@@ -223,7 +223,7 @@
             <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-javadoc-plugin</artifactId>
-              <version>2.8</version>
+              <version>2.10.1</version>
               <configuration>
                 <!--<aggregate>true</aggregate>-->
                 <excludePackageNames>org.slf4j.migrator:org.slf4j.migrator.*</excludePackageNames>

slf4j-api/src/main/java/org/slf4j/LoggerFactory.java

@@ -292,8 +292,17 @@ public final class LoggerFactory {
    * Return a logger named corresponding to the class passed as parameter, using
    * the statically bound {@link ILoggerFactory} instance.
    *
+   * <p>In case the the <code>clazz</code> parameter differs from the name of
+   * the caller as computed internally by SLF4J, a logger name mismatch warning will be 
+   * printed but only if the <code>slf4j.detectLoggerNameMismatch</code> system property is 
+   * set to true. By default, this property is not set and no warnings will be printed
+   * even in case of a logger name mismatch.
+   * 
    * @param clazz the returned logger will be named after clazz
    * @return logger
+   *
+   *
+   * @see <a href="http://www.slf4j.org/codes.html#loggerNameMismatch">Detected logger name mismatch</a> 
    */
   @Nonnull
   public static Logger getLogger(@Nonnull Class<?> clazz) {

slf4j-site/pom.xml

@@ -31,7 +31,7 @@
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-site-plugin</artifactId>
-        <version>3.3</version>
+        <version>${maven-site-plugin.version}</version>
         <configuration>
           <outputDirectory>${project.parent.basedir}/target/site
           </outputDirectory>

slf4j-site/src/site/pages/codes.html

@@ -89,23 +89,25 @@
     </p>
 
     <!-- ====================================================== -->
-    <h3 class="doAnchor" name="loggerNameMismatch">Detected logger name mismatch. </h3>
+    <h3 class="doAnchor" name="loggerNameMismatch">Detected logger
+    name mismatch. </h3>
 
-    <p><span class="label">inactive by default</span> Logger name
+    <p><span class="label notice">Note</span> Logger name mismatch
-    mismatch warnings are printed only if the
+    warnings are printed only if the
-    <code>slf4j.detectLoggerNameMismatch</code> system propery is set
+    <code>slf4j.detectLoggerNameMismatch</code> system property is set
-    to true.
+    to true. By default, this property is not set and no warnings will
+    be printed even in case of a logger name mismatch.
     </p>
 
-    <p>The warning will be printed in case the
+    <p>The warning will be printed in case the name of the logger
-    name of the logger specified via a class passed as an argument to
+    specified via a class passed as an argument to the
-    the LoggerFactory.getLogger(Class) method differs from the name of
+    <code>LoggerFactory.getLogger(Class)</code> method differs from
-    the caller as computed internally by SLF4J.
+    the name of the caller as computed internally by SLF4J.
     </p>
 
     <p>For example, the following code snippet</p> 
 
-<pre>package com.acme;
+<pre class="prettyprint source">package com.acme;
 import com.foo.Kangaroo;
 
 class <b>Fruit</b> {
@@ -114,26 +116,31 @@ class <b>Fruit</b> {
 
     <p>will result in the warning</p>
 
-    <pre>SLF4J: Detected logger name mismatch. Given name: "com.foo.Kangaroo"; computed name: "com.acme.Fruit".</pre>
+    <pre class="prettyprint source">SLF4J: Detected logger name mismatch. Given name: "com.foo.Kangaroo"; computed name: "com.acme.Fruit".</pre>
     
     <p>but only if <code>slf4j.detectLoggerNameMismatch</code> system
-    propery is set to true.</p>
+    property is set to true.</p>
     
     <p>No warning will be issued for the special case where the class
     in which the logger is defined is a super-type of the class
     parameter passed as argument. For example,</p>
     
-    <pre>abstract class A { 
+    <pre class="prettyprint source">class A { 
-    // no mismatch warning as class A is a super-type of class B
     Logger logger = LoggerFactory.getLogger(getClass()); 
 }
-class B extends A { }</pre>
+class B extends A { 
+    // no mismatch warning will be issued when B is instantiated 
+    // given that class A is a super-type of class B
+}</pre>
 
-    <p>In case you come across a mismatch warning which cannot be
+    <p>If you come across a mismatch warning which cannot be
-    explained, then you might have spotted a white elepahant, or a
+    explained, then you might have spotted a white elephant, that is a
     very rare occurrence where SLF4J cannot correctly compute the name
-    of the class where a logger is defined. Please do not hesitate to
+    of the class where a logger is defined. We are very interested to
-    file a <a href="bug-reporting.html">bug report</a>.
+    learn about cases where SLF4J fails to correclty compute the name
+    of the class where a logger is defined. If and when you spot such
+    a case, please do file a <a href="bug-reporting.html">bug
+    report</a> with us.
     </p>
 
     <!-- ====================================================== -->

slf4j-site/src/site/pages/manual.html

@@ -53,10 +53,11 @@
     users are highly encouraged to migrate to SLF4J 1.7.5 or later.
     </p>
 
-    <p><span class="label">since 1.7.8</span> <a
+    <p><span class="label">since 1.7.8</span> By setting he
-    href="codes.html#loggerNameMismatch">Spot incorrectly named
+    <code>slf4j.detectLoggerNameMismatch</code> system property to
-    loggers</a> by setting the <code>slf4j.detectLoggerNameMismatch</code>
+    true, SLF4J can automatically <a
-    system property to true.
+    href="codes.html#loggerNameMismatch">spot incorrectly named
+    loggers</a>.
     </p>
 
 

slf4j-site/src/site/pages/news.html

@@ -31,7 +31,6 @@
 
    <h3>14th of December, 2014 - Release of SLF4J 1.7.8 </h3>
 
-
    <p class="highlight"><a href="codes.html#loggerNameMismatch">Spot
    incorrectly named loggers</a> by setting the
    <code>slf4j.detectLoggerNameMismatch</code> system property to
@@ -40,7 +39,8 @@
    <p><a href="codes.html#loggerNameMismatch">Spot incorrectly named
    loggers</a> by setting the
    <code>slf4j.detectLoggerNameMismatch</code> system property to
-   true.</p>
+   true.  This significant feature was contributed by Alexander
+   Dorokhine.</p>
 
    <p>Added <code>MDC.putCloeable</code> method so that it can be used
    as a <a
@@ -54,6 +54,9 @@
    <p>Added JSR305 @Nonnull annotations in <code>LoggerFactory</code>
    class. Further annotations are likely to follow.</p> 
 
+   <p>Numerous small code improvements too minor to be listed
+   here.</p>
+
    <hr noshade="noshade" size="1"/>
 
    <h3>4th of April, 2014 - Release of SLF4J 1.7.7 </h3>