jdb/jlp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Finished documentation for v1.3

Browse Source 
* 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.
This commit is contained in:
Jonathan Bernard 2012-01-03 12:03:37 -06:00
parent 5028d38e35
commit 44c3412995
14 changed files with 146 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
lib/runtime/jar/groovy-all-1.7.10.jar
View File

Binary file not shown.

10
src/main/com/jdblabs/jlp/JLPBaseGenerator.groovy
View File

@ -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) {

24
src/main/com/jdblabs/jlp/JLPMain.groovy
View File

@ -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
/// library.
/// We are using Groovy's [CliBuilder] (a wrapper around the Apache
/// 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.

9
src/main/com/jdblabs/jlp/JLPParser.java
View File

@ -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
* be expanded in the future to be an abstract class implementing methods that
* take additional input for convenience.
* [`SourceFile`] given an input string. It may be expanded in the future to
* be an abstract class implementing methods that take additional input for
* convenience.
*
* [`SourceFile`]: jlp://jlp.jdb-labs.com/SourceFile
*
* @org jlp.jdb-labs.com/JLPParser
*/
public interface JLPParser {

66
src/main/com/jdblabs/jlp/JLPPegParser.java
View File

@ -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();

50
src/main/com/jdblabs/jlp/LiterateMarkdownGenerator.groovy
View File

@ -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
* uses [Markdown](http://daringfireball.net/projects/markdown/) to process the
* documentation into HTML output.
* The LiterateMarkdownGenerator is an implementation of [`JLPBaseGenerator`]
* that uses [Markdown] to process the 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
* implement them, as they are abstract on JLPBaseGenerator. */
/** We are not doing any parsing for [`CodeBlocks`] or [`DocTexts`]. We
* 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*.
* Each *SourceFile* becomes one ouput HTML file. This method is the entry
* point for a file to be emitted. */
/** @api Emit a [`SourceFile`].
* Each [`SourceFile`] becomes one ouput HTML file. This method is the
* 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) }

18
src/main/com/jdblabs/jlp/MarkdownParser.groovy
View File

@ -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)

2
src/main/com/jdblabs/jlp/Processor.groovy
View File

@ -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) {

2
src/main/com/jdblabs/jlp/TargetDoc.groovy
View File

@ -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

2
src/main/com/jdblabs/jlp/ast/Block.groovy
View File

@ -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 {

2
src/main/com/jdblabs/jlp/ast/CodeBlock.groovy
View File

@ -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 {

8
src/main/com/jdblabs/jlp/ast/Directive.groovy
View File

@ -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
* more information about link anchors.
* the [`LinkAnchor`] documentation for more information about link
* anchors.
*
* [`LinkAnchor`]: jlp://jlp.jdb-labs.com/LinkAnchor
*/
public static enum DirectiveType {
Api, Author, Copyright, Example, Include, Org;

2
src/main/com/jdblabs/jlp/ast/DocBlock.groovy
View File

@ -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 {

2
src/main/com/jdblabs/jlp/ast/DocText.groovy
View File

@ -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 {