Add some javadoc to the Sonar Channel module

4 files changed, 52 insertions, 4 deletions

diff --git a/sonar-channel/src/main/java/org/sonar/channel/Channel.java b/sonar-channel/src/main/java/org/sonar/channel/Channel.java
index b646a023435..0152a9145c7 100644
--- a/sonar-channel/src/main/java/org/sonar/channel/Channel.java
+++ b/sonar-channel/src/main/java/org/sonar/channel/Channel.java
@@ -21,5 +21,15 @@ package org.sonar.channel;
 
 public abstract class Channel<OUTPUT> {
 
+  /**
+   * Tries to consume the character stream at the current reading cursor position (provided by the {@link org.sonar.channel.CodeReader}). If
+   * the character stream is consumed the method must return true and the OUTPUT object can be fed.
+   * 
+   * @param code
+   *          the handle on the input character stream
+   * @param output
+   *          the OUTPUT that can be optionally fed by the Channel
+   * @return false if the Channel doesn't want to consume the character stream, true otherwise.
+   */
   public abstract boolean consume(CodeReader code, OUTPUT output);
 }
diff --git a/sonar-channel/src/main/java/org/sonar/channel/CodeReader.java b/sonar-channel/src/main/java/org/sonar/channel/CodeReader.java
index 8cb36a94d72..8d8673edbc1 100644
--- a/sonar-channel/src/main/java/org/sonar/channel/CodeReader.java
+++ b/sonar-channel/src/main/java/org/sonar/channel/CodeReader.java
@@ -24,10 +24,8 @@ import java.io.Reader;
 import java.util.regex.Matcher;
 
 /**
- * The CodeReader class provides all the basic features to lex a source code. Those features are :
- * <ul>
- * <li>Read and consume next characters until a regular expression is matched</li>
- * </ul>
+ * The CodeReader class provides some advanced features to read a source code. The most important one is the ability to try consuming the
+ * next characters in the stream according to a regular expression.
  */
 public class CodeReader extends CodeBuffer {
 
diff --git a/sonar-channel/src/main/java/org/sonar/channel/RegexChannel.java b/sonar-channel/src/main/java/org/sonar/channel/RegexChannel.java
index 8fdd074396c..cf44de7f3a8 100644
--- a/sonar-channel/src/main/java/org/sonar/channel/RegexChannel.java
+++ b/sonar-channel/src/main/java/org/sonar/channel/RegexChannel.java
@@ -22,12 +22,21 @@ package org.sonar.channel;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * The RegexChannel can be used to be called each time the next characters in the character stream match a regular expression
+ */
 public abstract class RegexChannel<OUTPUT> extends Channel<OUTPUT> {
 
   private final StringBuilder tmpBuilder = new StringBuilder();
   private final Matcher matcher;
   private final String regex;
 
+  /**
+   * Create a RegexChannel object with the required regular expression
+   * 
+   * @param regex
+   *          regular expression to be used to try matching the next characters in the stream
+   */
   public RegexChannel(String regex) {
     matcher = Pattern.compile(regex).matcher("");
     this.regex = regex;
@@ -52,5 +61,14 @@ public abstract class RegexChannel<OUTPUT> extends Channel<OUTPUT> {
     }
   }
 
+  /**
+   * The consume method is called each time the regular expression used to create the RegexChannel object matches the next characters in the
+   * character streams.
+   * 
+   * @param token
+   *          the token consumed in the character stream and matching the regular expression
+   * @param the
+   *          OUPUT object which can be optionally fed
+   */
   protected abstract void consume(CharSequence token, OUTPUT output);
 }
diff --git a/sonar-channel/src/main/java/org/sonar/channel/package-info.java b/sonar-channel/src/main/java/org/sonar/channel/package-info.java
new file mode 100644
index 00000000000..70820b6a8fa
--- /dev/null
+++ b/sonar-channel/src/main/java/org/sonar/channel/package-info.java
@@ -0,0 +1,22 @@
+/**
+ * Provides a basic framework to sequentially read any kind of character stream in order to feed a generic OUTPUT. 
+ * 
+ * This framework can used for instance in order to :
+ * <ul>
+ *   <li>Create a lexer in charge to generate a list of tokens from a character stream</li>
+ *   <li>Create a source code syntax highligther in charge to decorate a source code with HTML tags</li>
+ *   <li>Create a javadoc generator</li>
+ *   <li>...</li>
+ * </ul> 
+ * 
+ * The entry point of this framework is the {@link org.sonar.channel.ChannelDispatcher} class. 
+ * This class must be initialized with a {@link org.sonar.channel.CodeReader} and a list of {@link org.sonar.channel.Channel}.
+ * 
+ * The {@link org.sonar.channel.CodeReader} encapsulates any character stream in order to provide all mechanisms to Channels  
+ * in order to look ahead and look behind the current reading cursor position. 
+ * 
+ * A {@link org.sonar.channel.Channel} is in charge to consume the character stream through the CodeReader in order to feed
+ * the OUTPUT.
+ */
+package org.sonar.channel;
+