Updated Mojo documentation

antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java

@@ -66,9 +66,8 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * Goal that picks up all the ANTLR grammars in a project and moves those that
+ * Parses ANTLR 4 grammar files {@code *.g4} and transforms them into Java
- * are required for generation of the compilable sources into the location
+ * source files.
- * that we use to compile them, such as {@code target/generated-sources/antlr4}.
  *
  * @author Sam Harwell
  */
@@ -84,8 +83,8 @@ public class Antlr4Mojo extends AbstractMojo {
     //
 
     /**
-     * If set to true then the ANTLR tool will generate a description of the atn
+     * If set to true then the ANTLR tool will generate a description of the ATN
-     * for each rule in <a href="http://www.graphviz.org">Dot format</a>
+     * for each rule in <a href="http://www.graphviz.org">Dot format</a>.
      */
     @Parameter(property = "antlr4.atn", defaultValue = "false")
     protected boolean atn;
@@ -97,25 +96,25 @@ public class Antlr4Mojo extends AbstractMojo {
 	protected String encoding;
 
 	/**
-	 * generate parse tree listener (default)
+	 * Generate parse tree listener interface and base class.
 	 */
 	@Parameter(property = "antlr4.listener", defaultValue = "true")
 	protected boolean listener;
 
 	/**
-	 * generate parse tree visitor
+	 * Generate parse tree visitor interface and base class.
 	 */
 	@Parameter(property = "antlr4.visitor", defaultValue = "false")
 	protected boolean visitor;
 
 	/**
-	 * treat warnings as errors
+	 * Treat warnings as errors.
 	 */
 	@Parameter(property = "antlr4.treatWarningsAsErrors", defaultValue = "false")
 	protected boolean treatWarningsAsErrors;
 
 	/**
-	 * use the ATN simulator for all predictions
+	 * Use the ATN simulator for all predictions.
 	 */
 	@Parameter(property = "antlr4.forceATN", defaultValue = "false")
 	protected boolean forceATN;
@@ -135,38 +134,37 @@ public class Antlr4Mojo extends AbstractMojo {
 	protected List<String> arguments;
 
     /* --------------------------------------------------------------------
-     * The following are Maven specific parameters, rather than specificlly
+     * The following are Maven specific parameters, rather than specific
      * options that the ANTLR tool can use.
      */
 
 	/**
-     * Provides an explicit list of all the grammars that should
+	 * Provides an explicit list of all the grammars that should be included in
-     * be included in the generate phase of the plugin. Note that the plugin
+	 * the generate phase of the plugin. Note that the plugin is smart enough to
-     * is smart enough to realize that imported grammars should be included but
+	 * realize that imported grammars should be included but not acted upon
-     * not acted upon directly by the ANTLR Tool.
+	 * directly by the ANTLR Tool.
-     *
+	 * <p/>
-     * Unless otherwise specified, the include list scans for and includes all
+	 * A set of Ant-like inclusion patterns used to select files from the source
-     * files that end in ".g" in any directory beneath src/main/antlr4. Note that
+	 * directory for processing. By default, the pattern
-     * this version of the plugin looks for the directory antlr4 and not the directory
+	 * <code>**&#47;*.g4</code> is used to select grammar files.
-     * antlr, so as to avoid clashes and confusion for projects that use both v3 and v4 grammars
-     * such as ANTLR itself.
 	 */
     @Parameter
     protected Set<String> includes = new HashSet<String>();
     /**
-     * Provides an explicit list of any grammars that should be excluded from
+     * A set of Ant-like exclusion patterns used to prevent certain files from
-     * the generate phase of the plugin. Files listed here will not be sent for
+     * being processed. By default, this set is empty such that no files are
-     * processing by the ANTLR tool.
+     * excluded.
      */
     @Parameter
     protected Set<String> excludes = new HashSet<String>();
     /**
+     * The current Maven project.
      */
     @Parameter(property = "project", required = true, readonly = true)
     protected MavenProject project;
 
     /**
-     * Specifies the ANTLR directory containing grammar files.
+     * The directory where the ANTLR grammar files ({@code *.g4}) are located.
      */
 	@Parameter(defaultValue = "${basedir}/src/main/antlr4")
     private File sourceDirectory;
@@ -178,7 +176,7 @@ public class Antlr4Mojo extends AbstractMojo {
     private File outputDirectory;
 
     /**
-     * Specify location of grammars and tokens files.
+     * Specify location of imported grammars and tokens files.
      */
 	@Parameter(defaultValue = "${basedir}/src/main/antlr4/imports")
     private File libDirectory;
@@ -208,41 +206,27 @@ public class Antlr4Mojo extends AbstractMojo {
      * The main entry point for this Mojo, it is responsible for converting
      * ANTLR 4.x grammars into the target language specified by the grammar.
      *
-     * @throws MojoExecutionException When something is discovered such as a missing source
+     * @throws MojoExecutionException if a configuration or grammar error causes
-     * @throws MojoFailureException When something really bad happens such as not being able to create the ANTLR Tool
+     * the code generation process to fail
+     * @throws MojoFailureException if an instance of the ANTLR 4 {@link Tool}
+     * cannot be created
      */
     @Override
     public void execute() throws MojoExecutionException, MojoFailureException {
 
         Log log = getLog();
 
-        // Check to see if the user asked for debug information, then dump all the
-        // parameters we have picked up if they did.
-        //
         if (log.isDebugEnabled()) {
-
-            // Excludes
-            //
             for (String e : excludes) {
                 log.debug("ANTLR: Exclude: " + e);
             }
 
-            // Includes
-            //
             for (String e : includes) {
                 log.debug("ANTLR: Include: " + e);
             }
 
-            // Output location
-            //
             log.debug("ANTLR: Output: " + outputDirectory);
-
-            // Library directory
-            //
             log.debug("ANTLR: Library: " + libDirectory);
-
-            // Flags
-            //
         }
 
 		if (!sourceDirectory.isDirectory()) {
@@ -363,7 +347,7 @@ public class Antlr4Mojo extends AbstractMojo {
     /**
      *
      * @param sourceDirectory
-     * @throws org.codehaus.plexus.compiler.util.scan.InclusionScanException
+     * @throws InclusionScanException
      */
     @NotNull
     private List<List<String>> processGrammarFiles(List<String> args, File sourceDirectory) throws InclusionScanException {
@@ -445,7 +429,7 @@ public class Antlr4Mojo extends AbstractMojo {
      * relative to the base of the output directory and reflect the input
      * organization of the grammar files.
      *
-     * @param sourceDirectory The source directory File object
+     * @param sourceDirectory The source directory {@link File} object
      * @param grammarFileName The full path to the input grammar file
      * @return The path to the grammar file relative to the source directory
      */

antlr4-maven-plugin/src/site/apt/examples/import.apt

@@ -1,8 +1,8 @@
 Imported Grammar Files
 
  In order to have the ANTLR plugin automatically locate and use grammars used
- as imports in your main .g4 files, you need to place the imported grammar
+ as imports in your main <<<.g4>>> files, you need to place the imported grammar
- files in the imports directory beneath the root directory of your grammar
+ files in the <<<imports>>> directory beneath the root directory of your grammar
  files (which is <<<src/main/antlr4>>> by default of course).
 
  For a default layout, place your import grammars in the directory: <<<src/main/antlr4/imports>>>

antlr4-maven-plugin/src/site/apt/examples/libraries.apt

@@ -2,23 +2,23 @@ Libraries
 
  The introduction of the import directive in a grammar allows reuse of common grammar files
  as well as the ability to divide up functional components of large grammars. However it has
- caused some confusion in regard to the fact that generated vocab files (<<<xxx.tokens>>>) can also
+ caused some confusion in regard to the fact that generated vocabulary files (<<<*.tokens>>>) can also
  be searched for with the <<<<libDirectory>>>> directive.
 
  This has confused two separate functions and imposes a structure upon the layout of
  your grammar files in certain cases. If you have grammars that both use the import
- directive and also require the use of a vocab file then you will need to locate
+ directive and also require the use of a vocabulary file then you will need to locate
- the grammar that generates the .tokens file alongside the grammar that uses it. This
+ the grammar that generates the <<<.tokens>>> file alongside the grammar that uses it. This
  is because you will need to use the <<<<libDirectory>>>> directive to specify the
- location of your imported grammars and ANTLR will not find any vocab files in
+ location of your imported grammars and ANTLR will not find any vocabulary files in
  this directory.
 
- The .tokens files for any grammars are generated within the same output directory structure
+ The <<<.tokens>>> files for any grammars are generated within the same output directory structure
- as the .java files. So, whereever the .java files are generated, you will also find the .tokens
+ as the <<<.java>>> files. So, wherever the <<<.java>>> files are generated, you will also find the <<<.tokens>>>
- files. ANTLR looks for .tokens files in both the <<<<libDirectory>>>> and the output directory
+ files. ANTLR looks for <<<.tokens>>> files in both the <<<<libDirectory>>>> and the output directory
- where it is placing the geenrated .java files. Hence when you locate the grammars that generate
+ where it is placing the generated <<<.java>>> files. Hence when you locate the grammars that generate
- .tokens files in the same source directory as the ones that use the .tokens files, then
+ <<<.tokens>>> files in the same source directory as the ones that use the <<<.tokens>>> files, then
- the Maven plugin will find the expected .tokens files.
+ the Maven plugin will find the expected <<<.tokens>>> files.
 
  The <<<<libDirectory>>>> is specified like any other directory parameter in Maven. Here is an
  example:
@@ -30,7 +30,6 @@ Libraries
     <version>4.0-SNAPSHOT</version>
 
     <executions>
-
         <execution>
             <configuration>
                 <goals>

antlr4-maven-plugin/src/site/apt/examples/simple.apt

@@ -1,7 +1,7 @@
 Simple configuration
 
  If your grammar files are organized into the default locations as described in the {{{../index.html}introduction}},
- then configuring the pom.xml file for your project is as simple as adding this to it
+ then configuring the <<<pom.xml>>> file for your project is as simple as adding this to it
 
 +--
 <plugins>
@@ -21,12 +21,12 @@ Simple configuration
 </plugins>
 +--
 
- When the mvn command is executed all grammar files under <<<src/main/antlr4>>>, except any
+ When the <<<mvn>>> command is executed all grammar files under <<<src/main/antlr4>>>, except any
  import grammars under <<<src/main/antlr4/imports>>> will be analyzed and converted to
- java source code in the output directory <<<target/generated-sources/antlr4>>>.
+ Java source code in the output directory <<<target/generated-sources/antlr4>>>.
 
  Your input files under <<<antlr4>>> should be stored in sub directories that
- reflect the package structure of your java parsers. If your grammar file parser.g4 contains:
+ reflect the package structure of your java parsers. If your grammar file <<<parser.g4>>> contains:
 
 +---
 @header {
@@ -34,7 +34,7 @@ package org.jimi.themuss;
 }
 +---
 
- Then the .g4 file should be stored in: <<<src/main/antlr4/org/jimi/themuss/parser.g4>>>. THis way
+ Then the <<<.g4>>> file should be stored in: <<<src/main/antlr4/org/jimi/themuss/parser.g4>>>. This way
- the generated .java files will correctly reflect the package structure in which they will
+ the generated <<<.java>>> files will correctly reflect the package structure in which they will
  finally rest as classes.
 

antlr4-maven-plugin/src/site/apt/faq.apt.vm

@@ -0,0 +1 @@
+FAQ

antlr4-maven-plugin/src/site/apt/index.apt

@@ -28,7 +28,7 @@ ANTLR v4 Maven plugin
  use version 4.0 of the plugin, you will build your grammars using version 4.0 of the
  ANTLR tool, version 4.2 of the plugin will use version 4.2 of the ANTLR tool and so on.
 
- You may also find that there are patch versions of the plugin suchas 4.0-1 4.0-2 and
+ You may also find that there are patch versions of the plugin such as 4.0-1 4.0-2 and
  so on. Use the latest patch release of the plugin.
 
  The current version of the plugin is shown at the top of this page after the <<Last Deployed>> date.
@@ -49,10 +49,10 @@ ANTLR v4 Maven plugin
              +--- imports/  .g4 files that are imported by other grammars.
 +--
 
- If your grammar is intended to be part of a package called org.foo.bar then you would
+ If your grammar is intended to be part of a package called <<<org.foo.bar>>> then you would
  place it in the directory <<<src/main/antlr4/org/foo/bar>>>. The plugin will then produce
- .java and .tokens files in the output directory <<<target/generated-sources/antlr4/org/foo/bar>>>
+ <<<.java>>> and <<<.tokens>>> files in the output directory <<<target/generated-sources/antlr4/org/foo/bar>>>
- When the Java files are compiled they will be in the correct location for the javac
+ When the Java files are compiled they will be in the correct location for the Javac
  compiler without any special configuration. The generated java files are automatically
  submitted for compilation by the plugin.
 
@@ -60,4 +60,3 @@ ANTLR v4 Maven plugin
  any grammar files that are imported by other grammar files (do not make subdirectories here.)
  Such files are never built on their own, but the plugin will automatically tell the ANTLR
  tool to look in this directory for library files.
-

antlr4-maven-plugin/src/site/apt/usage.apt.vm

@@ -1,193 +1,59 @@
 Usage
 
- The Maven plugin for antlr is simple to use but is at its simplest when you use the default
+ The ANTLR 4 plugin for Maven can generate parsers for any number of grammars in
- layouts for your grammars, as so:
+ your project.
+
+* Compiling Grammars into Parsers
+
+ By default, the <<<{{{./antlr-mojo.html}antlr}}>>> goal will search for grammar
+ files in the directory <<<$\{basedir\}/src/main/antlr4>>> and any additional
+ <<<.tokens>>> files in the directory <<<$\{basedir\}/src/main/antlr4/imports>>>.
+ This can be configured to search other directories using the plugin configuration
+ parameters as described in the <<<{{{./antlr-mojo.html}antlr}}>>> goal
+ documentation.
+
+ The following figure shows the expected layout of files for the default
+ configuration of this plugin.
 
 +--
  src/main/
       |
       +--- antlr4/...       .g4 files organized in the required package structure
              |
-             +--- imports/  .g4 files that are imported by other grammars.
+             +--- imports/  user-created .tokens files and .g4 files that are imported by other grammars
 +--
 
- However, if you are not able to use this structure for whatever reason, you
+ The next step is to configure your POM to call the plugin. The goals will
- can configure the locations of the grammar files, where library/import files
+ normally run during the generate-sources phase of the build. Examples of how to
- are located and where the output files should be generated.
+ configure your POM can be found on the various examples pages, reachable via
-
+ the page menu. If you stick with the default values, the snippet below will
-* Plugin Descriptor
+ suffice:
-
- The current version of the plugin is shown at the top of this page after the <<Last Deployed>> date.
-
- The full layout of the descriptor (at least, those parts that are not standard Maven things),
- showing the default values of the configuration options, is as follows:
 
 +--
-<plugin>
+<project>
+  ...
+  <build>
+    <plugins>
+      <plugin>
         <groupId>org.antlr</groupId>
         <artifactId>antlr4-maven-plugin</artifactId>
-    <version>4.0-SNAPSHOT</version>
+        <version>${project.version}</version>
-
         <executions>
-        
           <execution>
-            <configuration>
+            <id>antlr</id>
             <goals>
               <goal>antlr</goal>
             </goals>
-                <conversionTimeout>10000</conversionTimeout>
-                <debug>false</debug>
-                <dfa>false</dfa>
-                <nfa>false</nfa>
-                <excludes><exclude/></excludes>
-                <includes><include/></includes>
-                <libDirectory>src/main/antlr4/imports</libDirectory>
-                <messageFormat>antlr</messageFormat>
-                <outputDirectory>target/generated-sources/antlr4</outputDirectory>
-                <printGrammar>false</printGrammar>
-                <profile>false</profile>
-                <report>false</report>
-                <sourceDirectory>src/main/antlr4</sourceDirectory>
-                <trace>false</trace>
-                <verbose>true</verbose>
-            </configuration>
           </execution>
         </executions>
-
+      </plugin>
-</plugin>
+    </plugins>
+    ...
+  </build>
+  ...
+</project>
 +--
 
- Note that you can create multiple executions, and thus build some grammars with different
+ Note that you can create multiple executions, and thus build some grammars with
- options to others (such as setting the debug option for instance).
+ different options to others (such as setting the <<<debug>>> option for
-
+ instance).
-** Configuration parameters
-
-*** report
-
-    If set to true, then after the tool has processed an input grammar file
-    it will report variaous statistics about the parser, such as information
-    on cyclic DFAs, which rules may use backtracking, and so on.
-
-    default-value="false"
-
-*** printGrammar
-
-    If set to true, then the ANTLR tool will print a version of the input
-    grammar which is devoid of any actions that may be present in the input file.
-
-    default-value = "false"
-
-*** debug
-
-     If set to true, then the code generated by the ANTLR code generator will
-     be set to debug mode. This means that when run, the code will 'hang' and
-     wait for a debug connection on a TCP port (49100 by default).
-     
-     default-value="false"
-     
-*** profile
-
-     If set to true, then then the generated parser will compute and report on
-     profile information at runtime.
-     
-     default-value="false"
-     
-*** nfa
-
-     If set to true then the ANTLR tool will generate a description of the nfa
-     for each rule in <a href="http://www.graphviz.org">Dot format</a>
-     
-     default-value="false"
-     
-    protected boolean nfa;
-    
-*** dfa
-
-     If set to true then the ANTLR tool will generate a description of the DFA
-     for each decision in the grammar in <a href="http://www.graphviz.org">Dot format</a>
-     
-     default-value="false"
-     
-*** trace
-
-     If set to true, the generated parser code will log rule entry and exit points
-     to stdout as an aid to debugging.
-     
-     default-value="false"
-     
-*** messageFormat
-
-     If this parameter is set, it indicates that any warning or error messages returned
-     by ANLTR, shoould be formatted in the specified way. Currently, ANTLR supports the
-     built-in formats of antlr, gnu and vs2005.
-
-     default-value="antlr"
-     
-*** verbose
-
-     If this parameter is set to true, then ANTLR will report all sorts of things
-     about what it is doing such as the names of files and the version of ANTLR and so on.
-     
-     default-value="true"
-     
-*** conversionTimeout
-
-     The number of milliseconds ANTLR will wait for analysis of each
-     alternative in the grammar to complete before giving up. You may raise
-     this value if ANTLR gives up on a complicated alt and tells you that
-     there are lots of ambiguties, but you know that it just needed to spend
-     more time on it. Note that this is an absolute time and not CPU time.
-     
-     default-value="10000"
-     
-*** includes
-
-     Provides an explicit list of all the grammars that should
-     be included in the generate phase of the plugin. Note that the plugin
-     is smart enough to realize that imported grammars should be included but
-     not acted upon directly by the ANTLR Tool.
-     
-     Unless otherwise specified, the include list scans for and includes all
-     files that end in ".g4" in any directory beneath src/main/antlr4. Note that
-     this version of the plugin looks for the directory antlr4 and not the directory
-     antlr, so as to avoid clashes and confusion for projects that use both v3 and v4 grammars
-     such as ANTLR itself.
-     
-*** excludes
-
-     Provides an explicit list of any grammars that should be excluded from
-     the generate phase of the plugin. Files listed here will not be sent for
-     processing by the ANTLR tool.
-     
-*** sourceDirectory
-
-     Specifies the Antlr directory containing grammar files. For
-     antlr version 4.x we default this to a directory in the tree
-     called antlr4 because the antlr directory is occupied by version
-     2.x grammars.
-
-     <<NB>> Take careful note that the default location for antlr grammars
-     is now <<antlr4>> and NOT <<antlr>>
-
-     default-value="<<<${basedir}/src/main/antlr4>>>"
-     
-*** outputDirectory
-
-     Location for generated Java files. For antlr version 4.x we default
-     this to a directory in the tree called antlr4 because the antlr
-     directory is occupied by version 2.x grammars.
-     
-     default-value="<<<${project.build.directory}/generated-sources/antlr4>>>"
-     
-*** libDirectory
-
-     Location for imported token files, e.g. <code>.tokens</code> and imported grammars.
-     Note that ANTLR will not try to process grammars that it finds in this directory, but
-     will include this directory in the search for .tokens files and import grammars.
-
-     <<NB>> If you change the lib directory from the default but the directory is
-     still under<<<${basedir}/src/main/antlr4>>>, then you will need to exclude
-     the grammars from processing specifically, using the <<<<excludes>>>> option.
-
-     default-value="<<<${basedir}/src/main/antlr4/imports>>>"
-

antlr4-maven-plugin/src/site/site.xml

@@ -17,7 +17,9 @@
 
     <menu name="Overview">
       <item name="Introduction" href="index.html"/>
+      <item name="Goals" href="plugin-info.html"/>
       <item name="Usage" href="usage.html"/>
+      <item name="FAQ" href="faq.html"/>
     </menu>
 
     <menu name="Examples">