Added @param directive.

project.properties

@@ -1,7 +1,7 @@
-#Tue, 13 Aug 2013 08:48:43 -0500
+#Fri, 30 May 2014 19:49:05 -0500
 name=jlp
-version=1.7
+version=1.8
-build.number=25
+build.number=6
 lib.local=true
 release.dir=release
 main.class=com.jdblabs.jlp.JLPMain

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

@@ -19,7 +19,7 @@ import org.slf4j.LoggerFactory
  */
 public class JLPMain {
 
-    public static final String VERSION = "1.7"
+    public static final String VERSION = "1.8"
 
     private static Logger log = LoggerFactory.getLogger(JLPMain.class)
 

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

@@ -40,8 +40,8 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      */
 
     /**
-     * #### Full constructor
+     * #### Full constructor.
-     * This allows the caller to specific all four of the comment delimiters
+     * This allows the caller to specify all four of the comment delimiters
      * recognized by the parser.
      */
     public JLPPegParser(String mdocStart, String mdocEnd,
@@ -52,6 +52,20 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
         SDOC_START = String(sdocStart).label("SDOC_START");
         MDOC_LINE_START = AnyOf(mdocLineStart).label("MDOC_LINE_START"); }
 
+    /**
+     * #### Full constructor supporting multiple comment types.
+     * This allows the caller to specify all four of the comment delimiters
+     * recognized by the parser, supplying multiple types of comment
+     * delimiters.
+     */
+    public JLPPegParser(List mdocStarts, List mdocEnds,
+        String mdocLineStarts, List sdocStart) {
+
+        MDOC_START = FirstOf(mdocStarts.toArray()).label("MDOC_START");
+        MDOC_END = FirstOf(mdocEnds.toArray()).label("MDOC_END");
+        SDOC_START = FirstOf(sdocStarts.toArray()).label("SDOC_START");
+        MDOC_LINE_START = AnyOf(mdocLineStart).label("MDOC_LINE_START"); }
+
     /**
      * #### Single-line comments only constructor.
      * This allows the caller to easily set up the parser to only recognize
@@ -292,7 +306,7 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      * Parses the rule:
      *
      *     SLongDirective =
-     *      (API_DIR / EXAMPLE_DIR) RemainingSDocLine SDocText?
+     *      (API_DIR / EXAMPLE_DIR / PARAM_DIR) RemainingSDocLine SDocText?
      *
      * Pushes a [`Directive`] node onto the stack.
      *
@@ -302,8 +316,8 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
         return Sequence(
             push(curLineNum),
 
-            FirstOf(API_DIR, EXAMPLE_DIR),  push(match()),
+            FirstOf(API_DIR, EXAMPLE_DIR, PARAM_DIR),   push(match()),
-            RemainingSDocLine(),            push(match()),
+            RemainingSDocLine(),                        push(match()),
 
             Optional(Sequence(
                 SDocText(),
@@ -318,7 +332,7 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
      * Parses the rule:
      *
      *     MLongDirective = 
-     *      (API_DIR / EXAMPLE_DIR) RemainingMDocLine MDocText?
+     *      (API_DIR / EXAMPLE_DIR / PARAM_DIR) RemainingMDocLine MDocText?
      *
      * Pushes a [`Directive`] node onto the stack.
      *
@@ -328,8 +342,8 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
         return Sequence(
             push(curLineNum),
 
-            FirstOf(API_DIR, EXAMPLE_DIR), push(match()),
+            FirstOf(API_DIR, EXAMPLE_DIR, PARAM_DIR),   push(match()),
-            RemainingMDocLine(),           push(match()),
+            RemainingMDocLine(),                        push(match()),
 
             Optional(Sequence(
                 MDocText(),
@@ -497,6 +511,7 @@ public class JLPPegParser extends BaseParser<Object> implements JLPParser {
     Rule EXAMPLE_DIR    = IgnoreCase("example");
     Rule INCLUDE_DIR    = IgnoreCase("include");
     Rule ORG_DIR        = IgnoreCase("org");
+    Rule PARAM_DIR      = IgnoreCase("param");
 
     /// #### Hard-coded terminals.
     Rule AT         = Ch('@').label("AT");

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

@@ -281,6 +281,9 @@ public class LiterateMarkdownGenerator extends JLPBaseGenerator {
             case DirectiveType.Example:
                 return directive.value
 
+            case DirectiveType.Param:
+                return "" // TODO: can we do better here, even though we're
+                           // not understanding the source yet?
             // TODO:
             // case DirectiveType.Include:
 

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

@@ -438,8 +438,8 @@ public class Processor {
                     break
                 case 'html': case 'xml':
                     parsers[sourceType] = Parboiled.createParser(
-                        JLPPegParser, '<!--', '-->',
+                        JLPPegParser, '<!--!', '-->',
-                        '#$%^&*()_-+=|;:\'",<>?~`', '<<?')
+                        '!#$%^&*()_-+=|;:\'",<>?~`', '<<?')
                     break
                 case 'sql':
                     parsers[sourceType] = Parboiled.createParser(JLPPegParser,

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

@@ -50,10 +50,15 @@ public class Directive extends ASTNode {
      *     the [`LinkAnchor`] documentation for more information about link
      *     anchors.
      *
+     * Param
+     * :   Used to document a parameter to a function, method, or subroutine.
+     *     This is typically used in API documentation, but no generator
+     *     currently knows how to do anything intelligent with this directive.
+     *
      * [`LinkAnchor`]: jlp://jlp.jdb-labs.com/LinkAnchor
      */
     public static enum DirectiveType {
-        Api, Author, Copyright, Example, Include, Org;
+        Api, Author, Copyright, Example, Include, Org, Param;
         
         public static DirectiveType parse(String typeString) {
             valueOf(typeString.toLowerCase().capitalize()) } }