[MSHARED-562] improved documentation
git-svn-id: https://svn.apache.org/repos/asf/maven/shared/trunk@1753019 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java
index 14047eb..d427640 100644
--- a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java
+++ b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/AnsiMessageBuffer.java
@@ -22,8 +22,8 @@
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
diff --git a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java
index 58283cf..c5c9d3d 100644
--- a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java
+++ b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageBuffer.java
@@ -110,21 +110,46 @@
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 );
}
diff --git a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java
index aee080e..a315976 100644
--- a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java
+++ b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/MessageUtils.java
@@ -23,8 +23,11 @@
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 @@
/**
* 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 @@
/**
* Is message color active: requires JAnsi available (through Maven) and the color has not been disabled.
- * @return
*/
public static boolean isColor()
{
diff --git a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java
index cd1a417..aa0c28e 100644
--- a/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java
+++ b/maven-shared-utils/src/main/java/org/apache/maven/shared/utils/logging/package-info.java
@@ -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
diff --git a/maven-shared-utils/src/site/apt/index.apt.vm b/maven-shared-utils/src/site/apt/index.apt.vm
index 38e007c..a7bbc88 100644
--- a/maven-shared-utils/src/site/apt/index.apt.vm
+++ b/maven-shared-utils/src/site/apt/index.apt.vm
@@ -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
