Class JJDocMojo

  • All Implemented Interfaces:
    org.apache.maven.plugin.ContextEnabled, org.apache.maven.plugin.Mojo, org.apache.maven.reporting.MavenMultiPageReport, org.apache.maven.reporting.MavenReport

    @Mojo(name="jjdoc")
    @Execute(phase=GENERATE_SOURCES)
    public class JJDocMojo
    extends org.apache.maven.reporting.AbstractMavenReport
    JJDoc takes a JavaCC parser specification and produces documentation for the BNF grammar. This mojo will search the source directory for all *.jj files and run JJDoc once for each file it finds. Each of these output files, along with an index.html file will be placed in the site directory (target/site/jjdoc), and a link will be created in the "Project Reports" menu of the generated site.
    Since:
    2.3
    See Also:
    JJDoc Documentation
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  JJDocMojo.GrammarInfoComparator
      Compares grammar infos using their relative grammar file paths as the sort key.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private java.lang.Boolean bnf
      A flag whether to generate a plain text document with the unformatted BNF.
      private java.lang.String cssHref
      The hypertext reference to an optional CSS file for the generated HTML documents.
      private java.io.File defaultGrammarDirectoryJavaCC
      The default source directory for hand-crafted grammar files.
      private java.io.File defaultGrammarDirectoryJJTree
      The default source directory for grammar files generated by JJTree.
      private java.io.File defaultGrammarDirectoryJTB
      The default source directory for grammar files generated by JTB.
      private java.lang.String grammarEncoding
      The file encoding to use for reading the grammar files.
      private java.lang.String jjdocDirectory
      The relative path of the JJDoc reports in the output directory.
      private boolean oneTable
      This option controls the structure of the generated HTML output.
      private java.io.File outputDirectory
      The destination directory where JJDoc saves the generated documentation files.
      private java.io.File[] sourceDirectories
      The directories where the JavaCC grammar files (*.jj) are located.
      private java.lang.Boolean text
      A flag to specify the output format for the generated documentation.
      • Fields inherited from class org.apache.maven.reporting.AbstractMavenReport

        locale, mojoExecution, outputFormat, outputTimestamp, project, reactorProjects, remoteProjectRepositories, repoSession, siteDirectory, siteRenderer, siteTool
      • Fields inherited from interface org.apache.maven.reporting.MavenReport

        CATEGORY_PROJECT_INFORMATION, CATEGORY_PROJECT_REPORTS, ROLE
      • Fields inherited from interface org.apache.maven.plugin.Mojo

        ROLE
    • Constructor Summary

      Constructors 
      Constructor Description
      JJDocMojo()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean canGenerateReport()  
      private void createReportFooter​(org.apache.maven.doxia.sink.Sink sink)
      Create the HTML footer for the report page.
      private void createReportHeader​(java.util.ResourceBundle bundle, org.apache.maven.doxia.sink.Sink sink)
      Create the header and title for the HTML report page.
      private void createReportLink​(org.apache.maven.doxia.sink.Sink sink, java.io.File sourceDirectory, java.io.File grammarFile, java.lang.String linkPath)
      Create a table row containing a link to the JJDoc report for a grammar file.
      void executeReport​(java.util.Locale locale)
      Run the actual report.
      void generate​(org.apache.maven.doxia.sink.Sink sink, java.util.Locale locale)  
      private java.util.ResourceBundle getBundle​(java.util.Locale locale)
      Get the resource bundle for the report text.
      java.lang.String getDescription​(java.util.Locale locale)  
      private java.io.File getJJDocOutputDirectory()
      Get the output directory of the JJDoc files, i.e.
      java.lang.String getName​(java.util.Locale locale)  
      protected java.lang.String getOutputDirectory()
      Get the output directory of the report if run directly from the command line.
      private java.lang.String getOutputFileExtension()
      The JJDoc output file will have a .html or .txt extension depending on the value of the parameters text and bnf.
      java.lang.String getOutputName()  
      private java.io.File[] getSourceDirectories()
      Get the source directories that should be scanned for grammar files.
      private JJDoc newJJDoc()
      Creates a new facade to invoke JJDoc.
      private GrammarInfo[] scanForGrammars​(java.io.File sourceDirectory)
      Searches the specified source directory to find grammar files that can be documented.
      • Methods inherited from class org.apache.maven.reporting.AbstractMavenReport

        closeReport, constructXrefLocation, execute, generate, getCategoryName, getInputEncoding, getLocale, getOutputEncoding, getProject, getReportOutputDirectory, getSink, getSinkFactory, getSiteRenderer, getXrefLocation, isExternalReport, setReportOutputDirectory
      • Methods inherited from class org.apache.maven.plugin.AbstractMojo

        getLog, getPluginContext, setLog, setPluginContext
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface org.apache.maven.reporting.MavenReport

        getOutputPath
    • Field Detail

      • sourceDirectories

        @Parameter
        private java.io.File[] sourceDirectories
        The directories where the JavaCC grammar files (*.jj) are located. By default, the directories ${basedir}/src/main/javacc, ${project.build.directory}/generated-sources/jjtree and ${project.build.directory}/generated-sources/jtb are scanned for grammar files to document.
      • defaultGrammarDirectoryJavaCC

        @Parameter(defaultValue="${basedir}/src/main/javacc")
        private java.io.File defaultGrammarDirectoryJavaCC
        The default source directory for hand-crafted grammar files.
      • defaultGrammarDirectoryJJTree

        @Parameter(defaultValue="${project.build.directory}/generated-sources/jjtree")
        private java.io.File defaultGrammarDirectoryJJTree
        The default source directory for grammar files generated by JJTree.
      • defaultGrammarDirectoryJTB

        @Parameter(defaultValue="${project.build.directory}/generated-sources/jtb")
        private java.io.File defaultGrammarDirectoryJTB
        The default source directory for grammar files generated by JTB.
      • jjdocDirectory

        @Parameter(defaultValue="jjdoc")
        private java.lang.String jjdocDirectory
        The relative path of the JJDoc reports in the output directory. This path will be appended to the output directory.
      • outputDirectory

        @Parameter(defaultValue="${project.reporting.outputDirectory}",
                   property="javacc.outputDirectory")
        private java.io.File outputDirectory
        The destination directory where JJDoc saves the generated documentation files. 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.
      • grammarEncoding

        @Parameter(defaultValue="${project.build.sourceEncoding}",
                   property="javacc.grammarEncoding")
        private java.lang.String grammarEncoding
        The file encoding to use for reading the grammar files.
        Since:
        2.6
      • cssHref

        @Parameter(property="javacc.cssHref")
        private java.lang.String cssHref
        The hypertext reference to an optional CSS file for the generated HTML documents. If specified, this CSS file will be included via a <link> element in the HTML documents. Otherwise, the default style will be used.
        Since:
        2.5
      • text

        @Parameter(property="javacc.text")
        private java.lang.Boolean text
        A flag to specify the output format for the generated documentation. If set to true, JJDoc will generate a plain text description of the BNF. Some formatting is done via tab characters, but the intention is to leave it as plain as possible. Specifying false causes JJDoc to generate a hyperlinked HTML document unless the parameter bnf has been set to true. Default value is false.
      • bnf

        @Parameter(property="javacc.bnf")
        private java.lang.Boolean bnf
        A flag whether to generate a plain text document with the unformatted BNF. Note that setting this option to true is only effective if the parameter text is false. Default value is false.
        Since:
        2.6
      • oneTable

        @Parameter(property="javacc.oneTable",
                   defaultValue="true")
        private boolean oneTable
        This option controls the structure of the generated HTML output. If set to true, a single HTML table for the entire BNF is generated. Setting it to false will produce one table for every production in the grammar.
    • Constructor Detail

      • JJDocMojo

        public JJDocMojo()
    • Method Detail

      • getOutputDirectory

        protected java.lang.String getOutputDirectory()
        Get the output directory of the report if run directly from the command line.
        Overrides:
        getOutputDirectory in class org.apache.maven.reporting.AbstractMavenReport
        Returns:
        The report output directory.
        See Also:
        AbstractMavenReport.getOutputDirectory()
      • getJJDocOutputDirectory

        private java.io.File getJJDocOutputDirectory()
        Get the output directory of the JJDoc files, i.e. the sub directory in the report output directory as specified by the jjdocDirectory parameter.
        Returns:
        The report output directory of the JJDoc files.
      • getSourceDirectories

        private java.io.File[] getSourceDirectories()
        Get the source directories that should be scanned for grammar files.
        Returns:
        The source directories that should be scanned for grammar files, never null.
      • getName

        public java.lang.String getName​(java.util.Locale locale)
        Parameters:
        locale - The locale to use for this report.
        Returns:
        The name of this report.
        See Also:
        MavenReport.getName(java.util.Locale)
      • getDescription

        public java.lang.String getDescription​(java.util.Locale locale)
        Parameters:
        locale - The locale to use for this report.
        Returns:
        The description of this report.
        See Also:
        MavenReport.getDescription(java.util.Locale)
      • getOutputName

        public java.lang.String getOutputName()
        Returns:
        The name of the main report file.
        See Also:
        MavenReport.getOutputName()
      • canGenerateReport

        public boolean canGenerateReport()
        Specified by:
        canGenerateReport in interface org.apache.maven.reporting.MavenReport
        Overrides:
        canGenerateReport in class org.apache.maven.reporting.AbstractMavenReport
        Returns:
        true if the configured source directories are not empty, false otherwise.
        See Also:
        MavenReport.canGenerateReport()
      • executeReport

        public void executeReport​(java.util.Locale locale)
                           throws org.apache.maven.reporting.MavenReportException
        Run the actual report.
        Specified by:
        executeReport in class org.apache.maven.reporting.AbstractMavenReport
        Parameters:
        locale - The locale to use for this report.
        Throws:
        org.apache.maven.reporting.MavenReportException - If the report generation failed.
      • getOutputFileExtension

        private java.lang.String getOutputFileExtension()
        The JJDoc output file will have a .html or .txt extension depending on the value of the parameters text and bnf.
        Returns:
        The file extension (including the leading period) to be used for the JJDoc output files.
      • createReportHeader

        private void createReportHeader​(java.util.ResourceBundle bundle,
                                        org.apache.maven.doxia.sink.Sink sink)
        Create the header and title for the HTML report page.
        Parameters:
        bundle - The resource bundle with the text.
        sink - The sink for writing to the main report file.
      • createReportLink

        private void createReportLink​(org.apache.maven.doxia.sink.Sink sink,
                                      java.io.File sourceDirectory,
                                      java.io.File grammarFile,
                                      java.lang.String linkPath)
        Create a table row containing a link to the JJDoc report for a grammar file.
        Parameters:
        sink - The sink to write the report
        sourceDirectory - The source directory of the grammar file.
        grammarFile - The JavaCC grammar file.
        linkPath - The path to the JJDoc output.
      • createReportFooter

        private void createReportFooter​(org.apache.maven.doxia.sink.Sink sink)
        Create the HTML footer for the report page.
        Parameters:
        sink - The sink to write the HTML report page.
      • newJJDoc

        private JJDoc newJJDoc()
        Creates a new facade to invoke JJDoc. Most options for the invocation are derived from the current values of the corresponding mojo parameters. The caller is responsible to set the input file and output file on the returned facade.
        Returns:
        The facade for the tool invocation, never null.
      • scanForGrammars

        private GrammarInfo[] scanForGrammars​(java.io.File sourceDirectory)
                                       throws org.apache.maven.reporting.MavenReportException
        Searches the specified source directory to find grammar files that can be documented.
        Parameters:
        sourceDirectory - The source directory to scan for grammar files.
        Returns:
        An array of grammar infos describing the found grammar files or null if the source directory does not exist.
        Throws:
        org.apache.maven.reporting.MavenReportException - If there is a problem while scanning for .jj files.
      • getBundle

        private java.util.ResourceBundle getBundle​(java.util.Locale locale)
        Get the resource bundle for the report text.
        Parameters:
        locale - The locale to use for this report.
        Returns:
        The resource bundle.
      • generate

        public void generate​(org.apache.maven.doxia.sink.Sink sink,
                             java.util.Locale locale)
                      throws org.apache.maven.reporting.MavenReportException
        Specified by:
        generate in interface org.apache.maven.reporting.MavenReport
        Overrides:
        generate in class org.apache.maven.reporting.AbstractMavenReport
        Throws:
        org.apache.maven.reporting.MavenReportException