Finished documentation for v1.3

* Finished the initial documentation for version 1.3. I do not believe the
  documentation for a project is ever 'finished'. As long as the code is still
  evolving, the documentation is evolving. Having said that, the documentation
  is now caught up with the code for version 1.3.
* Removed an old dependany on groovy 1.7.10. This dependancy is now satisfied by
  the build script based on the version of Groovy used on the system performing
  the build.

src/main/com/jdblabs/jlp/JLPBaseGenerator.groovy

@@ -16,7 +16,7 @@ import java.util.Map
 public abstract class JLPBaseGenerator {
 
     /**
-     * The generator works in close conjunction with the JLP Processor.
+     * The generator works in close conjunction with a JLP Processor.
      * This tight coupling in intended for these two classes. The distiction
      * between the two classes is scope. The Processor class is concerned with
      * data and behavior common to the whole documentation process whereas the
@@ -39,15 +39,17 @@ public abstract class JLPBaseGenerator {
      *
      * The **parse** phase allows the Generator to build up facts about the
      * file being processed before emitting the documentation in the **emit**
-     * phase. There is a `parse` method for each `ASTNode` type. The default
+     * phase. There is a `parse` method for each [`ASTNode`] type. The default
      * implementation for JLPBaseGenerator calls the `parse` methods in such a
-     * way that it visits each ASTNode in the file.
+     * way that it visits each `ASTNode` in the file.
      *
      * The **emit** phase is where the Generator creates the documentation for
-     * each AST node. Unlike the parse phase, there is no default implementation
+     * each `ASTNode`. Unlike the parse phase, there is no default implementation
      * for the emit phase as emitting the final result will be very dependant on
      * the emitter.
      *
+     * [`ASTNode`]: jlp://jlp.jdb-labs.com/ast/ASTNode
+     *
      * @org com.jdb-labs.jlp.JLPBaseGenerator/phases
      */
     protected void parse(SourceFile sourceFile) {

src/main/com/jdblabs/jlp/JLPMain.groovy

@@ -25,20 +25,38 @@ public class JLPMain {
     public static void main(String[] args) {
 
         /// #### Define command-line options.
-        /// We are using the Groovy wrapper around the Apache Commons CLI
+        /// We are using Groovy's [CliBuilder] (a wrapper around the Apache
-        /// library.
+        /// Commons library).
+        ///
+        /// [CliBuilder]: http://groovy.codehaus.org/gapi/groovy/util/CliBuilder.html
         CliBuilder cli = new CliBuilder(
             usage: 'jlp [options] <src-file> <src-file> ...')
 
-        // define options
+        /// -h, --help
+        /// :   Print help information.
         cli.h('Print this help information.', longOpt: 'help', required: false)
+
+        /// -o, --outputdir
+        /// :   Set the output directory where the documentation will be
+        ///     written.
         cli.o("Output directory (defaults to 'jlp-docs').",
             longOpt: 'output-dir', args: 1, argName: "output-dir",
             required: false)
+
+        /// --css-file
+        /// :   Specify an alternate CSS file for the output documentation.
         cli._('Use <css-file> for the documentation css.',
             longOpt: 'css-file', args: 1, required: false, argName: 'css-file')
+
+        /// --relative-path-root
+        /// :   Override the current working directory. This is useful if you
+        ///     are invoking jlp remotely, or if the current working directory
+        ///     is incorrectly set by the executing environment.
         cli._(longOpt: 'relative-path-root', args: 1, required: false,
             'Resolve all relative paths against this root.')
+
+        /// --version
+        /// :   Display JLP versioning information.
         cli._(longOpt: 'version', 'Display the JLP version information.')
 
         /// #### Parse the options.

src/main/com/jdblabs/jlp/JLPParser.java

@@ -8,9 +8,12 @@ import com.jdblabs.jlp.ast.SourceFile;
 
 /**
  * JLPParser is a simple interface. It has one method to return a parsed
- * [`SourceFile`](jlp://jlp.jdb-labs.com/SourceFile) given an input string. It may
+ * [`SourceFile`] given an input string. It may be expanded in the future to
- * be expanded in the future to be an abstract class implementing methods that
+ * be an abstract class implementing methods that take additional input for
- * take additional input for convenience.
+ * convenience.
+ *
+ * [`SourceFile`]: jlp://jlp.jdb-labs.com/SourceFile
+ *
  * @org jlp.jdb-labs.com/JLPParser
  */
 public interface JLPParser {

src/main/com/jdblabs/jlp/JLPPegParser.java

@@ -88,7 +88,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     SourceFile = (Block / DocBlock / CodeBlock)+
      *
-     * Pushes a SourceFile node on the stack.
+     * Pushes a [`SourceFile`] node on the stack.
+     *
+     * [`SourceFile`}: jlp://jlp.jdb-labs.com/ast/SourceFile
      */
     public Rule SourceFile() {
         return Sequence(
@@ -160,7 +162,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     Block = DocBlock CodeBlock
      *
-     * Pushes a Block onto the stack
+     * Pushes a [`Block`] onto the stack.
+     *
+     * [`Block`]: jlp://jlp.jdb-labs.com/ast/Block
      */
     Rule Block() {
         return Sequence(
@@ -178,7 +182,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     DocBlock = SDocBlock / MDocBlock
      *
-     * Pushes a DocBlock onto the stack.
+     * Pushes a [`DocBlock`] onto the stack.
+     *
+     * [`DocBlock`]: jlp://jlp.jdb-labs.com/ast/DocBlock
      */
     Rule DocBlock() { return FirstOf(SDocBlock(), MDocBlock()); }
 
@@ -188,7 +194,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     SDocBlock = (SDirective / SDocText)+
      *
-     * Pushes a DocBlock object onto the stack
+     * Pushes a [`DocBlock`] onto the stack.
+     *
+     * [`DocBlock`]: jlp://jlp.jdb-labs.com/ast/DocBlock
      */
     Rule SDocBlock() {
         return Sequence(
@@ -203,7 +211,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     MDocBlock = MDOC_START (MDirective / MDocText)+ MDOC_END
      *
-     * Pushes a DocBlock object onto the stack
+     * Pushes a [`DocBlock`] onto the stack.
+     *
+     * [`DocBlock`]: jlp://jlp.jdb-labs.com/ast/DocBlock
      */
     Rule MDocBlock() {
         return Sequence(
@@ -223,7 +233,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     CodeBlock = (RemainingCodeLine)+
      *
-     * Pushes a CodeBlock onto the stack.
+     * Pushes a [`CodeBlock`] onto the stack.
+     *
+     * [`CodeBlock`]: jlp://jlp.jdb-labs.com/ast/CodeBlock
      */
     Rule CodeBlock() {
         return Sequence(
@@ -237,7 +249,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     SDirective = SDocLineStart AT (SLongDirective / SShortDirective)
      *
-     * Pushes a Directive node on the stack.
+     * Pushes a [`Directive`] node on the stack.
+     *
+     * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
      */
     Rule SDirective() {
         return Sequence(
@@ -249,7 +263,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     MDirective = MDocLineStart? AT (MLongDirective / MShortDirective)
      *
-     * Pushes a Directive node onto the stack.
+     * Pushes a [`Directive`] node onto the stack.
+     *
+     * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
      */
     Rule MDirective() {
         return Sequence(
@@ -263,7 +279,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *     SLongDirective =
      *      (API_DIR / EXAMPLE_DIR) RemainingSDocLine SDocText?
      *
-     * Pushes a Directive node onto the stack.
+     * Pushes a [`Directive`] node onto the stack.
+     *
+     * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
      */
     Rule SLongDirective() {
         return Sequence(
@@ -287,7 +305,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *     MLongDirective = 
      *      (API_DIR / EXAMPLE_DIR) RemainingMDocLine MDocText?
      *
-     * Pushes a Directive node onto the stack.
+     * Pushes a [`Directive`] node onto the stack.
+     *
+     * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
      */
     Rule MLongDirective() {
         return Sequence(
@@ -312,7 +332,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *       (AUTHOR_DIR / ORG_DIR / INCLUDE_DIR / COPYRIGHT_DIR)
      *       RemainingSDocLine
      *
-     * Pushes a Directive node onto the stack.
+     * Pushes a [`Directive`] node onto the stack.
+     *
+     * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
      */
     Rule SShortDirective() {
         return Sequence(
@@ -331,7 +353,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *       (AUTHOR_DIR / ORG_DIR / INCLUDE_DIR / COPYRIGHT_DIR)
      *       RemainingMDocLine
      *
-     * Pushes a Directive node onto the stack.
+     * Pushes a [`Directive`] node onto the stack.
+     *
+     * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
      */
     Rule MShortDirective() {
         return Sequence(
@@ -348,7 +372,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     SDocText = (SDocLineStart !AT RemainingSDocLine)+
      *
-     * Pushes a DocText node onto the stack.
+     * Pushes a [`DocText`] node onto the stack.
+     *
+     * [`DocText`]: jlp://jlp.jdb-labs.com/ast/DocText
      */
     Rule SDocText() {
         return Sequence(
@@ -363,7 +389,9 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      *
      *     MDocText = (MDocLineStart? !AT RemainingMDocLine)+
      *
-     * Pushes a DocText node onto the stack.
+     * Pushes a [`DocText`] node onto the stack.
+     *
+     * [`DocText`]: jlp://jlp.jdb-labs.com/ast/DocText
      */
     Rule MDocText() {
         return Sequence(
@@ -481,8 +509,10 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
 
     /**
      * #### addToDocBlock
-     * Add the given block to the SourceFile node expected to be at the top of
+     * Add the given block to the [`SourceFile`] node expected to be at the top of
      * the parser value stack.
+     *
+     * [`SourceFile`]: jlp://jlp.jdb-labs.com/ast/SourceFile
      */
     boolean addBlockToSourceFile(Block block) {
         ((SourceFile) peek()).blocks.add(block);
@@ -490,8 +520,12 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
 
     /**
      * #### addToDocBlock
-     * Add the given Directive or DocText to the DocBlock expected to be at the
+     * Add the given [`Directive`] or [`DocText`] to the [`DocBlock`] expected to be at the
      * top of the parser value stack.
+     *
+     * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
+     * [`DocText`]: jlp://jlp.jdb-labs.com/ast/DocText
+     * [`DocBlock`]: jlp://jlp.jdb-labs.com/ast/DocBlock
      */
     boolean addToDocBlock(ASTNode an) {
         DocBlock docBlock = (DocBlock) pop();

src/main/com/jdblabs/jlp/LiterateMarkdownGenerator.groovy

@@ -15,14 +15,17 @@ import static org.apache.commons.lang3.StringEscapeUtils.escapeHtml4 as escape
 import java.util.List
 
 /**
- * The LiterateMarkdownGenerator is an implementation of JLPBaseGenerator that
+ * The LiterateMarkdownGenerator is an implementation of [`JLPBaseGenerator`]
- * uses [Markdown](http://daringfireball.net/projects/markdown/) to process the
+ * that uses [Markdown] to process the documentation into HTML output.
- * documentation into HTML output.
+ *
+ * [`JLPBaseGenerator`]: jlp://jlp.jdb-labs.com/JLPBaseGenerator
+ * [Markdown]: http://daringfireball.net/projects/markdown/
  * @org jlp.jdb-labs.com/LiterateMarkdownGenerator
  */
 public class LiterateMarkdownGenerator extends JLPBaseGenerator {
 
-    /// We will use the PegDown library for generating the Markdown output.
+    /// We will use the [PegDown](https://github.com/sirthias/pegdown) library
+    /// for generating the Markdown output.
     protected PegDownProcessor pegdown
 
     public LiterateMarkdownGenerator(Processor processor) {
@@ -35,9 +38,12 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
     /** ### Parse phase implementation. ###  */
     //  ===================================
 
-    /** Implement the parse phase for *Directive* nodes. We are interested
+    /** Implement the parse phase for [`Directive`] nodes. We are interested
       * specifically in saving the link anchor information from *org*
-      * directives. */
+      * directives.
+      *
+      * [`Directive`]: jlp://jlp.jdb-labs.com/ast/Directive
+      */
     protected void parse(Directive directive) {
         switch(directive.type) {
             case DirectiveType.Org:
@@ -52,8 +58,13 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
                 break // do nothing
             } }
 
-    /** We are not doing any parsing for *CodeBlocks* or *DocTexts*. We have to
+    /** We are not doing any parsing for [`CodeBlocks`] or [`DocTexts`]. We
-      * implement them, as they are abstract on JLPBaseGenerator. */
+      * have to implement them, as they are abstract on [`JLPBaseGenerator`].
+      *
+      * [`CodeBlocks`]: jlp://jlp.jdb-labs.com/ast/CodeBlock
+      * [`DocTexts`]: jlp://jlp.jdb-labs.com/ast/DocText
+      * [`JLPBaseGenerator`]: jlp://jlp.jdb-labs.com/JLPBaseGenerator
+      */
     protected void parse(CodeBlock codeBlock) {} // nothing to do
     protected void parse(DocText docText) {} // nothing to do
 
@@ -61,9 +72,12 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
     /** ### Emit phase implementation. ###  */
     //  ==================================
 
-    /** @api Emit a *SourceFile*.
+    /** @api Emit a [`SourceFile`].
-      * Each *SourceFile* becomes one ouput HTML file. This method is the entry
+      * Each [`SourceFile`] becomes one ouput HTML file. This method is the
-      * point for a file to be emitted. */
+      * entry point for a file to be emitted.
+      *
+      * [`SourceFile`]: jlp://jlp.jdb-labs.com/ast/SourceFile
+      */
     protected String emit(SourceFile sourceFile) {
         StringBuilder sb = new StringBuilder()
 
@@ -125,7 +139,7 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
 
         return sb.toString() }
 
-    /** @api Emit a *Block*. */
+    /** @api Emit a [`Block`](jlp://jlp.jdb-labs.com/ast/Block). */
     protected String emit(Block block) {
         StringBuilder sb = new StringBuilder()
 
@@ -153,7 +167,7 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
         /// Close the table row.
         sb.append('</tr>') }
 
-    /** @api Emit a *DocBlock*. */
+    /** @api Emit a [`DocBlock`](jlp://jlp/jdb-labs.com/ast/DocBlock). */
     protected String emit(DocBlock docBlock) {
         /// Create a queue for the doc block elements, we are going to 
         /// sort them by type and line number
@@ -199,7 +213,7 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
         return processMarkdown(sb.toString())
     }
 
-    /** @api Emit a *CodeBlock*. */
+    /** @api Emit a [`CodeBlock`](jlp://jlp.jdb-labs.com/ast/CodeBlock). */
     protected String emit(CodeBlock codeBlock) {
         def codeLines
 
@@ -216,10 +230,10 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
         return "<pre class=\"brush: ${processor.currentDoc.sourceType};\">" +
             "${escape(codeLines.join(''))}</pre>" }
 
-    /** @api Emit a *DocText*. */
+    /** @api Emit a [`DocText`](jlp://jlp.jdb-labs.com/ast/DocText). */
     protected String emit(DocText docText) { return docText.value }
 
-    /** @api Emit a *Directive*. */
+    /** @api Emit a [`Directive`](jlp://jlp.jdb-labs.com/ast/Directive). */
     protected String emit(Directive directive) {
         switch(directive.type) {
 
@@ -264,7 +278,9 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
 
         return html; }
 
-    /// Shortcut for `processor.resolveLink(url, processor.currentDoc)`.
+    /// Shortcut for [`processor.resolveLink(url, processor.currentDoc)`][RL].
+    ///
+    /// [RL]: jlp://jlp.jdb-labs.com/Processor/resolveLink
     protected String resolveLink(String url) {
         processor.resolveLink(url, processor.currentDoc) }
 

src/main/com/jdblabs/jlp/MarkdownParser.groovy

@@ -7,12 +7,30 @@ package com.jdblabs.jlp
 import com.jdblabs.jlp.ast.*
 
 /**
+ * `MarkdownParser` handles `markdown` source files. This parser allows JLP to
+ * process plain Markdown files along with the other source files. This is
+ * useful as it allows the author to include pages that are pure documentation
+ * living alongside the documented source code. Examples would be an overview
+ * page, or a quick start guide to the codebase. This parser creates the bare
+ * minimum AST structure to include one [`DocBloc`] with the full contents of
+ * the source Markdown file.
+ *
+ * [`DocBlock`]: jlp://jlp.jdb-labs.com/ast/DocBlock
  * @org jlp.jdb-labs.com/MarkdownParser
  */
 public class MarkdownParser implements JLPParser {
 
     public SourceFile parse(String input) {
 
+        /*** Our AST structure will look like this:
+           *
+           *     SourceFile
+           *       Block
+           *         DocBlock
+           *           DocText
+           *             <file-contents>
+           *         CodeBlock
+           */
         def sourceFile = new SourceFile()
         def block
         def docBlock = new DocBlock(0)

src/main/com/jdblabs/jlp/Processor.groovy

@@ -198,6 +198,8 @@ public class Processor {
      *
      * *relative path (no leading `/`)*
      * :   Returns the link resolved against the `TargetDoc` passed in.
+     *
+     * @org jlp.jdb-labs.com/Processor/resolveLink
      */
     public String resolveLink(String link, TargetDoc targetDoc) {
         switch (link) {

src/main/com/jdblabs/jlp/TargetDoc.groovy

@@ -20,7 +20,7 @@ public class TargetDoc {
     public String sourceDocId
 
     /// The source code type (ie. `java`, `erlang`, etc.). See
-    /// [Processor.sourceTypeForFile](jlp.jdb-labs.com/Processor/sourceTypeForFile)
+    /// [`Processor.sourceTypeForFile`](jlp.jdb-labs.com/Processor/sourceTypeForFile)
     public String sourceType
 
     public String output

src/main/com/jdblabs/jlp/ast/Block.groovy

@@ -5,7 +5,7 @@
 package com.jdblabs.jlp.ast
 
 /**
- * ASTNode for *Blocks*.
+ * ASTNode for `Blocks`.
  * @org jlp.jdb-labs.com/ast/Block
  */
 public class Block extends ASTNode {

src/main/com/jdblabs/jlp/ast/CodeBlock.groovy

@@ -8,7 +8,7 @@ package com.jdblabs.jlp.ast
 import java.util.Map
 
 /**
- * @api ASTNode for *CodeBlock*s.
+ * @api ASTNode for `CodeBlocks`.
  * @org jlp.jdb-labs.com/ast/CodeBlock
  */
 public class CodeBlock extends ASTNode {

src/main/com/jdblabs/jlp/ast/Directive.groovy

@@ -5,7 +5,7 @@
 package com.jdblabs.jlp.ast
 
 /**
- * @api ASTNode for *Directive*s.
+ * @api ASTNode for `Directives`.
  * A documentation directive allows the author to add metadata and processing
  * instructions.
  * @org jlp.jdb-labs.com/ast/Directive
@@ -46,8 +46,10 @@ public class Directive extends ASTNode {
      * Org
      * :   Used to create a link anchor in the documentation. The `jlp` protocol
      *     in a URL allows the author to link back to a link anchor. Refer to
-     *     the [LinkAnchor](jlp://jlp.jdb-labs.com/LinkAnchor) documentation for
+     *     the [`LinkAnchor`] documentation for more information about link
-     *     more information about link anchors.
+     *     anchors.
+     *
+     * [`LinkAnchor`]: jlp://jlp.jdb-labs.com/LinkAnchor
      */
     public static enum DirectiveType {
         Api, Author, Copyright, Example, Include, Org;

src/main/com/jdblabs/jlp/ast/DocBlock.groovy

@@ -8,7 +8,7 @@ import java.util.ArrayList
 import java.util.List
 
 /**
- * @api ASTNode for *DocBlock*s.
+ * @api ASTNode for `DocBlocks`.
  * @org jlp.jdb-labs.com/ast/DocBlock
  */
 public class DocBlock extends ASTNode {

src/main/com/jdblabs/jlp/ast/DocText.groovy

@@ -5,7 +5,7 @@
 package com.jdblabs.jlp.ast
 
 /**
- * @api ASTNode for *DocText*s.
+ * @api ASTNode for `DocTexts`.
  * @org jlp.jdb-labs.com/ast/DocText
  */
 public class DocText extends ASTNode {