Built by Maven

javacc:jjdoc

Note:

This goal should be used as a Maven report.

Full name:

org.javacc.plugin:javacc-maven-plugin:3.8.0-SNAPSHOT:jjdoc

Description:

The jjdoc goal, for producing documentation for a JavaCC / JJTree / JTB grammar.
It is used indirectly under the hood when using the plugin as a reporting plugin, triggered by the Maven site plugin, producing JJDoc reports. In that case there can be only one execution and one configuration defining the source directories and other parameters.
It can also be used directly as a standalone goal, as a build plugin, if one wants more control, for example for multiple executions with different configurations with different sets of source directories and other parameters.
It searches the source directories for all grammar files (those included and not excluded) and runs JJDoc once for each file it finds, producing output files of the format set through the JJDoc options, and of names set through JJDoc options OUTPUT_DIRECTORY and OUTPUT_FILE.
It also produces, for each execution, an HTML "index" file named through the plugin parameter jjdocReportsPage containing a table with the hyperlinks for the grammar file name to its corresponding generated JJDoc document, in a directory set by a plugin parameter jjdocReportsDirectory if used in a build plugin or by the Maven site plugin parameter outputDirectory if used in a reporting plugin.
And finally, if used in a reporting plugin, the Maven site plugin will create a menu entry to the HTML "index" page in the "Project Documentation / Project Reports" menu of the site.

Detailed information about the JJDoc options can be found on the JJDoc documentation page.
Examples can be found in the integration tests jjdoc-goal and site-phase.
The code repositories can be found within JavaCC at GitHub and JTB at GitHub.

Attributes:

  • Requires a Maven project to be executed.
  • The goal is thread-safe and supports parallel builds.
  • Since version: 3.8.0.
  • Binds by default to the lifecycle phase: generate-sources.

Required Parameters

Name Type Since Description
<outputDirectory> File - The shared output directory for the report. Note that this parameter is only evaluated if the goal is run directly from the command line. If the goal is run indirectly as part of a site generation, the shared output directory configured in the Maven Site Plugin is used instead.

A plugin may use any subdirectory structure (either using a hard-coded name or, ideally, an additional user-defined mojo parameter with a default value) to generate multi-page reports or external reports with the main output file (entry point) denoted by #getOutputName().


Default: ${project.build.directory}/reports

Optional Parameters

Name Type Since Description
<excludes> String[] - The set of Ant-like exclusion patterns used to prevent certain files from being processed.
By default, this set is empty such that no files are excluded.
<failOnGrammarError> String - The fail on grammar error parameter.
It governs governs how the plugin will handle the errors it encountered while trying to read a grammar file to retrieve the parser name (and the parser package for languages that use it) (and in an execution the plugin may process zero, one or many grammars).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin stops processing other grammars and reports an error for the build;
if set to last, the error message is displayed, the plugin continues processing other grammars and at the end it reports an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin does not report an error for the current execution (i.e. it continues with the next execution).
Default: first
User Property: javacc.failOnGrammarError
<failOnPluginError> Boolean - The fail on plugin error flag.
It governs governs how the plugin will handle the errors it encountered on general configuration (i.e. parameters not related to grammars).
Possible values are true and false.
On an error: if set to false, the error message is displayed, the execution terminates, but the plugin does not report an error for the current execution (i.e. it continues with the next execution);
if set to true the error message is displayed, the execution terminates and the plugin reports an error for the build.
Default: true
User Property: javacc.failOnPluginError
<failOnProcessorError> String - The fail on processor error parameter.
It governs how the plugin will handle the errors returned by the processor invocations and the plugin post-processor copy operations (in an execution the plugin may process zero, one or many grammars and invoke one or more processors for each).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin stops processing other grammars and reports an error for the build;
if set to last, the error message is displayed, the plugin continues processing other grammars and at the end it reports an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin does not report an error for the current execution (i.e. it continues with the next execution).
Default: first
User Property: javacc.failOnProcessorError
<includes> String[] - The set of Ant-like inclusion patterns used to select files from the source directory for processing.
By default, the pattern is:
**/*.jj, **/*.jjt, **/*.jtb for the jjdoc goal.
<jjdocCmdLineArgs> List<String> - The list of single full command line arguments, which should be in the form accepted by JJDoc.

No arguments are read and used by the plugin.

The list will be passed as it is to JJDoc, no control nor modification is done by the plugin.
Note that JJDoc can internally pass some options to the parser it calls.

The list has no default value.

Example:


<jjdocCmdLineArgs>
  <arg>-CODE_GENERATOR="C#"</arg>
  <arg>-BNF=true</arg>
  <arg>-CSS="src/main/resources/my_css"</arg>
</jjdocCmdLineArgs>

Note that the javaccCmdLineArgs parameter is of type List<String>, which implies that the inner tags names can have any names and may be appear many times (like arg above).
Note also that if the project has a parent which also configures the plugin with parameters (to factorize them for the children for example), the child parameters will complement / replace the parent's ones for those that are absent / present in the parent; so
  • if one wants to get rid of (all) the parent's ones, he must use the combine.self="override" attribute at the list level in the child, and
  • if one wants to replace some of the parent's ones and add new ones in the child it is recommended to use distinct tag names in the parent, the same tag names in the child for those that must be replaced and another tag name or other tag names for the new ones.
See also Processor parameters.
User Property: javacc.jjdocCmdLineArgs
<jjdocReportsDirectory> File - The output directory where Maven / Doxia generates the HTML files summarizing the JJDoc reports generation.
Note that this parameter is only relevant if the goal is run from the command line or from the default build lifecycle.
If the goal is run indirectly as part of a site generation, the output directory configured in the Maven Site Plugin is used instead (it will usually be "${project.build.directory}/site").

Note that this is not the directory where JJDoc itself generates its reports, which must be set by the JJDoc OUTPUT_DIRECTORY option.


Default: ${project.build.directory}/generated-jjdoc
User Property: javacc.jjdocReportsDirectory
<jjdocReportsPage> String - The HTML page name (with extension), relative to the output directory, where Maven / Doxia generates the table of the JJDoc reports for the current execution.
Use a non default value for each of multiple executions, to differentiate reports.
Default: /jjdoc-reports.html
User Property: javacc.jjdocReportsPage
<locale> String - The locale to use when the report generation is invoked directly as a standalone Mojo.
See also: org.apache.maven.doxia.tools.SiteTool.DEFAULT_LOCALE, org.apache.maven.doxia.tools.SiteTool.getSiteLocales(java.lang.String)
Default: default
<outputFormat> String - The report output format: null by default, to represent a site, but can be configured to a Doxia Sink id.
User Property: output.format
<outputTimestamp> String - Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).
Default: ${project.build.outputTimestamp}
<siteDirectory> File - Directory containing the site.xml file.
Default: ${basedir}/src/site
<skip> Boolean - The skip processing flag.
If true, no goal will not be executed.
Default: false
User Property: javacc.skip
<sourceDirectories> List<File> - The directories where the grammar files are located.
They all must exist and be directories, otherwise a plugin error will be raised.
These directories will be recursively scanned for input files to pass to JavaCC.
Note that they will be under a common configuration; so if one wants a pom to process source directories with different configuration, he must configure multiple executions with different source directories.
The parameters includes and excludes can be used to select a subset of the files.
If not absolute paths, maven internals considers they ar relative to ${basedir} and converts them accordingly to absolute paths (i.e. src/main/javacc will be considered as ${basedir}/src/main/javacc, but /src/main/javacc will be considered as an absolute path, usually leading to an error.
The default value, adequate for a user written grammar, but not for a generated (by a preprocessor) grammar, is the array:
${basedir}/src/main/javacc, ${basedir}/src/main/jjtree, ${basedir}/src/main/jtb.
User Property: javacc.sourceDirectories

Parameter Details

<excludes>

The set of Ant-like exclusion patterns used to prevent certain files from being processed.
By default, this set is empty such that no files are excluded.
  • Type: java.lang.String[]
  • Required: No

<failOnGrammarError>

The fail on grammar error parameter.
It governs governs how the plugin will handle the errors it encountered while trying to read a grammar file to retrieve the parser name (and the parser package for languages that use it) (and in an execution the plugin may process zero, one or many grammars).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin stops processing other grammars and reports an error for the build;
if set to last, the error message is displayed, the plugin continues processing other grammars and at the end it reports an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin does not report an error for the current execution (i.e. it continues with the next execution).
  • Type: java.lang.String
  • Required: No
  • User Property: javacc.failOnGrammarError
  • Default: first

<failOnPluginError>

The fail on plugin error flag.
It governs governs how the plugin will handle the errors it encountered on general configuration (i.e. parameters not related to grammars).
Possible values are true and false.
On an error: if set to false, the error message is displayed, the execution terminates, but the plugin does not report an error for the current execution (i.e. it continues with the next execution);
if set to true the error message is displayed, the execution terminates and the plugin reports an error for the build.
  • Type: java.lang.Boolean
  • Required: No
  • User Property: javacc.failOnPluginError
  • Default: true

<failOnProcessorError>

The fail on processor error parameter.
It governs how the plugin will handle the errors returned by the processor invocations and the plugin post-processor copy operations (in an execution the plugin may process zero, one or many grammars and invoke one or more processors for each).
Possible values are first, last and ignore.
If set to first, the error message is displayed, the plugin stops processing other grammars and reports an error for the build;
if set to last, the error message is displayed, the plugin continues processing other grammars and at the end it reports an error for the build;
if set to ignore the error message(s) is(are) displayed but the plugin does not report an error for the current execution (i.e. it continues with the next execution).
  • Type: java.lang.String
  • Required: No
  • User Property: javacc.failOnProcessorError
  • Default: first

<includes>

The set of Ant-like inclusion patterns used to select files from the source directory for processing.
By default, the pattern is:
**/*.jj, **/*.jjt, **/*.jtb for the jjdoc goal.
  • Type: java.lang.String[]
  • Required: No

<jjdocCmdLineArgs>

The list of single full command line arguments, which should be in the form accepted by JJDoc.

No arguments are read and used by the plugin.

The list will be passed as it is to JJDoc, no control nor modification is done by the plugin.
Note that JJDoc can internally pass some options to the parser it calls.

The list has no default value.

Example:


<jjdocCmdLineArgs>
  <arg>-CODE_GENERATOR="C#"</arg>
  <arg>-BNF=true</arg>
  <arg>-CSS="src/main/resources/my_css"</arg>
</jjdocCmdLineArgs>

Note that the javaccCmdLineArgs parameter is of type List<String>, which implies that the inner tags names can have any names and may be appear many times (like arg above).
Note also that if the project has a parent which also configures the plugin with parameters (to factorize them for the children for example), the child parameters will complement / replace the parent's ones for those that are absent / present in the parent; so
  • if one wants to get rid of (all) the parent's ones, he must use the combine.self="override" attribute at the list level in the child, and
  • if one wants to replace some of the parent's ones and add new ones in the child it is recommended to use distinct tag names in the parent, the same tag names in the child for those that must be replaced and another tag name or other tag names for the new ones.
See also Processor parameters.
  • Type: java.util.List<java.lang.String>
  • Required: No
  • User Property: javacc.jjdocCmdLineArgs

<jjdocReportsDirectory>

The output directory where Maven / Doxia generates the HTML files summarizing the JJDoc reports generation.
Note that this parameter is only relevant if the goal is run from the command line or from the default build lifecycle.
If the goal is run indirectly as part of a site generation, the output directory configured in the Maven Site Plugin is used instead (it will usually be "${project.build.directory}/site").

Note that this is not the directory where JJDoc itself generates its reports, which must be set by the JJDoc OUTPUT_DIRECTORY option.

  • Type: java.io.File
  • Required: No
  • User Property: javacc.jjdocReportsDirectory
  • Default: ${project.build.directory}/generated-jjdoc

<jjdocReportsPage>

The HTML page name (with extension), relative to the output directory, where Maven / Doxia generates the table of the JJDoc reports for the current execution.
Use a non default value for each of multiple executions, to differentiate reports.
  • Type: java.lang.String
  • Required: No
  • User Property: javacc.jjdocReportsPage
  • Default: /jjdoc-reports.html

<locale>

The locale to use when the report generation is invoked directly as a standalone Mojo.
See also: org.apache.maven.doxia.tools.SiteTool.DEFAULT_LOCALE, org.apache.maven.doxia.tools.SiteTool.getSiteLocales(java.lang.String)
  • Type: java.lang.String
  • Required: No
  • Default: default

<outputDirectory>

The shared output directory for the report. Note that this parameter is only evaluated if the goal is run directly from the command line. If the goal is run indirectly as part of a site generation, the shared output directory configured in the Maven Site Plugin is used instead.

A plugin may use any subdirectory structure (either using a hard-coded name or, ideally, an additional user-defined mojo parameter with a default value) to generate multi-page reports or external reports with the main output file (entry point) denoted by #getOutputName().

  • Type: java.io.File
  • Required: Yes
  • Default: ${project.build.directory}/reports

<outputFormat>

The report output format: null by default, to represent a site, but can be configured to a Doxia Sink id.
  • Type: java.lang.String
  • Required: No
  • User Property: output.format

<outputTimestamp>

Timestamp for reproducible output archive entries, either formatted as ISO 8601 yyyy-MM-dd'T'HH:mm:ssXXX or as an int representing seconds since the epoch (like SOURCE_DATE_EPOCH).
  • Type: java.lang.String
  • Required: No
  • Default: ${project.build.outputTimestamp}

<siteDirectory>

Directory containing the site.xml file.
  • Type: java.io.File
  • Required: No
  • Default: ${basedir}/src/site

<skip>

The skip processing flag.
If true, no goal will not be executed.
  • Type: java.lang.Boolean
  • Required: No
  • User Property: javacc.skip
  • Default: false

<sourceDirectories>

The directories where the grammar files are located.
They all must exist and be directories, otherwise a plugin error will be raised.
These directories will be recursively scanned for input files to pass to JavaCC.
Note that they will be under a common configuration; so if one wants a pom to process source directories with different configuration, he must configure multiple executions with different source directories.
The parameters includes and excludes can be used to select a subset of the files.
If not absolute paths, maven internals considers they ar relative to ${basedir} and converts them accordingly to absolute paths (i.e. src/main/javacc will be considered as ${basedir}/src/main/javacc, but /src/main/javacc will be considered as an absolute path, usually leading to an error.
The default value, adequate for a user written grammar, but not for a generated (by a preprocessor) grammar, is the array:
${basedir}/src/main/javacc, ${basedir}/src/main/jjtree, ${basedir}/src/main/jtb.
  • Type: java.util.List<java.io.File>
  • Required: No
  • User Property: javacc.sourceDirectories