added notes about logger name, with Plexus Logger API that cannot follow logger name as class name convention :(

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-3/trunk@1412766 13f79535-47bb-0310-9956-ffa450edef68

maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLogger.java

@@ -22,7 +22,8 @@
 import org.codehaus.plexus.logging.Logger;
 
 /**
- * Adapt an SLF4J logger to a Plexus logger.
+ * Adapt an SLF4J logger to a Plexus logger, ignoring Plexus logger API parts that are not classical and
+ * probably not really used.
  * 
  * @author Jason van Zyl
  */
@@ -112,15 +113,24 @@ public boolean isFatalErrorEnabled()
         return logger.isErrorEnabled();
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public int getThreshold()
     {
         return 0;
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void setThreshold( int threshold )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public Logger getChildLogger( String name )
     {
         return null;

maven-embedder/src/main/java/org/apache/maven/cli/logging/Slf4jLoggerManager.java

@@ -25,7 +25,8 @@
 import org.slf4j.LoggerFactory;
 
 /**
- * Use an SLF4J {@link org.slf4j.ILoggerFactory} as a backing for a Plexus {@link org.codehaus.plexus.logging.LoggerManager}.
+ * Use an SLF4J {@link org.slf4j.ILoggerFactory} as a backing for a Plexus {@link org.codehaus.plexus.logging.LoggerManager},
+ * ignoring Plexus logger API parts that are not classical and probably not really used.
  *
  * @author Jason van Zyl
  * @since 3.1
@@ -46,37 +47,61 @@ public Logger getLoggerForComponent( String role )
         return new Slf4jLogger( loggerFactory.getLogger( role ) );
     }
 
+    /**
+     * The logger name for a component with a non-null hint is <code>role.hint</code>.
+     * <b>Warning</b>: this does not conform to logger name as class name convention.
+     * (and what about <code>null</code> and <code>default</code> hint equivalence?)
+     */
     public Logger getLoggerForComponent( String role, String hint )
     {
         return ( null == hint
             ? getLoggerForComponent( role )
-            : new Slf4jLogger( loggerFactory.getLogger( role + "." + hint ) ) );
+            : new Slf4jLogger( loggerFactory.getLogger( role + '.' + hint ) ) );
     }
 
     //
     // Trying to give loggers back is a bad idea. Ceki said so :-)
+    // notice to self: what was this method supposed to do?
     //
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void returnComponentLogger( String role )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void returnComponentLogger( String role, String hint )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public int getThreshold()
     {
         return 0;
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void setThreshold( int threshold )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored.
+     */
     public void setThresholds( int threshold )
     {
     }
 
+    /**
+     * <b>Warning</b>: ignored (always return <code>0</code>).
+     */
     public int getActiveLoggerCount()
     {
         return 0;

maven-embedder/src/site/apt/logging.apt

@@ -50,3 +50,16 @@ public class Wombat
    final Logger logger = LoggerFactory.getLogger(Wombat.class);
 }
 +-----
+
+* Logger Name
+
+ Before Maven 3.1.0, with logging implementation done in Maven, logger name wasn't used: they are as-is, without clear definition.
+
+ Starting with Maven 3.1.0, logging implementation can be of greatest use if logger names are well defined. This definition still
+ needs to be defined and implemented:
+
+ * classical "class name" pattern?
+
+ * Maven-specific name hierarchy?
+
+ * a mix (some with class name, some with Maven-specific hierarchy)?