Author: hboutemy Date: Sun Jul 17 07:32:56 2016 New Revision: 1753019 URL: http://svn.apache.org/viewvc?rev=1753019&view=rev Log: [MSHARED-562] improved documentation
Modified: maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java maven/shared/trunk/maven-shared-utils/src/site/apt/index.apt.vm Modified: maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java?rev=1753019&r1=1753018&r2=1753019&view=diff ============================================================================== --- maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java (original) +++ maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java Sun Jul 17 07:32:56 2016 @@ -22,8 +22,8 @@ package org.apache.maven.shared.utils.lo import org.fusesource.jansi.Ansi; /** - * Message buffer implementation that supports ANSI colors through JAnsi with configurable - * styles through {@link Style}. + * Message buffer implementation that supports ANSI colors through <a href="http://fusesource.github.io/jansi/">Jansi</a> + * with configurable styles through {@link Style}. */ class AnsiMessageBuffer implements MessageBuffer Modified: maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java?rev=1753019&r1=1753018&r2=1753019&view=diff ============================================================================== --- maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java (original) +++ maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java Sun Jul 17 07:32:56 2016 @@ -110,21 +110,46 @@ public interface MessageBuffer MessageBuffer project( Object message ); // - // message building methods (modelled after Ansi methods) + // message building methods modelled after Ansi methods // + /** + * Reset to default style. + */ MessageBuffer reset(); + /** + * Append content to the buffer. + */ MessageBuffer a( char[] value, int offset, int len ); + /** + * Append content to the buffer. + */ MessageBuffer a( char[] value ); + /** + * Append content to the buffer. + */ MessageBuffer a( CharSequence value, int start, int end ); + /** + * Append content to the buffer. + */ MessageBuffer a( CharSequence value ); + /** + * Append content to the buffer. + */ MessageBuffer a( Object value ); + /** + * Append a newline to the buffer. + */ MessageBuffer newline(); + /** + * Append formatted content to the buffer. + * @see String#format(String, Object...) + */ MessageBuffer format( String pattern, Object... args ); } Modified: maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java?rev=1753019&r1=1753018&r2=1753019&view=diff ============================================================================== --- maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java (original) +++ maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java Sun Jul 17 07:32:56 2016 @@ -23,8 +23,11 @@ import org.fusesource.jansi.Ansi; import org.fusesource.jansi.AnsiConsole; /** - * Colored message utils, to manage colors colors consistently across plugins (only if Maven version is at least 3.4). - * For Maven version before 3.4, message built with this util will never add color. + * Colored message utils, to manage colors colors consistently across plugins (only if Maven version is at least 3.4.0). + * For Maven version before 3.4.0, message built with this util will never add color. + * <p> + * Internally, <a href="http://fusesource.github.io/jansi/">Jansi</a> is used to render + * <a href="https://en.wikipedia.org/wiki/ANSI_escape_code#Colors">ANSI colors</a> on any platform. */ public class MessageUtils { @@ -47,6 +50,7 @@ public class MessageUtils /** * Install color support. + * This method is called by Maven core, and calling it is not necessary in plugins. */ public static void systemInstall() { @@ -78,7 +82,6 @@ public class MessageUtils /** * Is message color active: requires JAnsi available (through Maven) and the color has not been disabled. - * @return */ public static boolean isColor() { Modified: maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java?rev=1753019&r1=1753018&r2=1753019&view=diff ============================================================================== --- maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java (original) +++ maven/shared/trunk/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java Sun Jul 17 07:32:56 2016 @@ -33,7 +33,7 @@ * <li><code>success</code>, <code>failure</code>, <code>strong</code>, <code>mojo</code> and <code>project</code> for * message content</li> * </ul> - * Default styles colors can be configured through system properties, that can be set in <code>MAVEN_OPTS</code> + * Default styles colors can be overridden through system properties, that can be set in <code>MAVEN_OPTS</code> * environment variable (eventually in <code>.mavenrc</code> script):<ul> * <li>system properties are named <code>style.<style name></code>,</li> * <li>values are comma separated combination of <code>bold</code>, <code><color></code> and Modified: maven/shared/trunk/maven-shared-utils/src/site/apt/index.apt.vm URL: http://svn.apache.org/viewvc/maven/shared/trunk/maven-shared-utils/src/site/apt/index.apt.vm?rev=1753019&r1=1753018&r2=1753019&view=diff ============================================================================== --- maven/shared/trunk/maven-shared-utils/src/site/apt/index.apt.vm (original) +++ maven/shared/trunk/maven-shared-utils/src/site/apt/index.apt.vm Sun Jul 17 07:32:56 2016 @@ -30,17 +30,20 @@ ${project.name} This project aims to be a functional replacement for - {{{http://plexus.codehaus.org/plexus-utils}plexus-utils}} in Maven. + {{{http://codehaus-plexus.github.io/plexus-utils/}plexus-utils}} in Maven. It is not a 100% API compatible replacement though but a replacement <with improvements>: lots of methods got cleaned up, generics got added and we dropped a lot of unused code. -Why ? + Then there are additions, like + {{{apidocs/org/apache/maven/shared/utils/logging/package-summary.html}styled message API}}. + +Why? plexus-utils consisted mostly of code that was forked from various apache projects. - maven-shared-utils is based on the original from the apache sources. + maven-shared-utils is based on the original from the Apache sources. -Why not commons ? +Why not commons? We would prefer code to use commons-* code where appropriate, but the plexus-utils became slightly incompatible (different) from the commons over the years, so migrating is not