adding support for the -l lenient flag to the maven report.

README.md

@@ -1,11 +1,11 @@
 jsdoc3-maven-plugin
 ===================
 
-An automatic documentation generator for JavaScript within the Maven build lifecycle.
+An automatic documentation generator for JavaScript within the Maven Reporting lifecycle.
 
 ## What is the jsdoc3-maven-plugin? ##
 The jsdoc3-maven-plugin is a [modern maven plugin](http://maven.apache.org/plugin-tools/maven-plugin-plugin/examples/using-annotations.html)
-built for the purposes of generating [jsdoc](http://usejsdoc.org/) along with the Maven build lifecycle.  By default, the
+built for the purposes of generating [jsdoc](http://usejsdoc.org/) along with the Maven Reporting lifecycle.  By default, the
 plugin will bind to the _site_ phase, though this is configurable as with any other Maven plugin with goals.
 
 ## Getting Started ##
@@ -15,6 +15,10 @@ available through [Sonatype](http://www.sonatype.org/) and is synchronized with
 ## Release ##
 The current release version is 1.0.4, using jsdoc3 [3.2](https://github.com/jsdoc3/jsdoc/branches/releases/3.2).
 
+## Deprecation Notice ##
+Usage of this plugin as a build plugin is now deprecated.  Support for execution of this plugin within project.build.plugins
+will be dropped with release version 1.1.0.  Examples below reflect modern usage as a reporting plugin.
+
 ## Current Status ##
 [![Build Status](https://travis-ci.org/phasebash/jsdoc3-maven-plugin.png)](https://travis-ci.org/phasebash/jsdoc3-maven-plugin)
 
@@ -88,6 +92,7 @@ The current release version is 1.0.4, using jsdoc3 [3.2](https://github.com/jsdo
 ## Mojo Parameters ##
 * directoryRoots - File[]: An Array of Files which will be used as directory roots, any file within this directory will be included into the final jsdoc argument list.
 * recursive (Optional) - Boolean: A flag to indicate whether or not all directory roots should be searched and all files included recursively.
+* lenient (Optional) - Boolean: A flag to indicate whether or not the generator should tolerate errors (false), or keep plodding along despite them (true).
 * sourceFiles (Optional) - File[]: An Array of Files which will be included into the final jsdoc argument list.
 * outputDirectory (Optional) - File: The place where jsdoc should be written.  default: "${project.build.directory}/site/jsdoc"
 * includePrivate (Optional) - Boolean: A flag to indicate whether @private symbols are included in the generated documentation.

jsdoc3-maven-plugin/src/main/java/com/github/phasebash/jsdoc3/maven/JsDocMavenReport.java

@@ -50,21 +50,10 @@ public class JsDocMavenReport extends AbstractMavenReport {
     @Parameter(required = false)
     private File[] sourceFiles;
 
-    @Parameter(required = false)
-    private boolean recursive = true;
-
     /** the output directory for jsdoc */
     @Parameter(required = true, defaultValue = "${project.build.directory}/site/jsdoc")
     private File outputDirectory;
 
-    /** if debug mode should be invoked (includes debug rhino console) */
-    @Parameter(required = true, defaultValue = "false")
-    private boolean debug;
-
-    /** if private symbols should in included in documentation. */
-    @Parameter(required = true, defaultValue = "false")
-    private boolean includePrivate;
-
     /**
      * If a tutorials directory will be provided to jsdoc to resolve tutorial links.
      * see: http://usejsdoc.org/about-tutorials.html
@@ -79,6 +68,29 @@ public class JsDocMavenReport extends AbstractMavenReport {
     @Parameter(required = false)
     private File configFile;
 
+    /**
+     * If the processor should recurse into directory roots.
+     */
+    @Parameter(required = false)
+    private boolean recursive = true;
+
+    /**
+     * Should errors in jsdoc fail the process (false), or should the generator
+     * be lenient to errors (true).
+     *
+     * See: http://usejsdoc.org/about-commandline.html
+     */
+    @Parameter(required = false)
+    private boolean lenient = false;
+
+    /** if debug mode should be invoked (includes debug rhino console) */
+    @Parameter(required = true, defaultValue = "false")
+    private boolean debug;
+
+    /** if private symbols should in included in documentation. */
+    @Parameter(required = true, defaultValue = "false")
+    private boolean includePrivate;
+
     @Override
     protected Renderer getSiteRenderer() {
         return siteRenderer;
@@ -107,6 +119,7 @@ protected void executeReport(Locale locale) throws MavenReportException {
         builder.withLog(log);
         builder.withDebug(debug);
         builder.withRecursive(recursive);
+        builder.withLeniency(lenient);
         builder.withIncludePrivate(includePrivate);
         builder.withSourceFiles(sourceFiles);
         builder.withDirectoryRoots(directoryRoots);

jsdoc3-maven-plugin/src/main/java/com/github/phasebash/jsdoc3/maven/tasks/JsDocArgumentBuilder.java

@@ -45,6 +45,10 @@ public List<String> build(TaskContext context) {
             arguments.add("-r");
         }
 
+        if (context.isLenient()) {
+            arguments.add("-l");
+        }
+
         if (context.getConfigFile() != null) {
             arguments.add("-c");
             arguments.add(context.getConfigFile().toString());

jsdoc3-maven-plugin/src/main/java/com/github/phasebash/jsdoc3/maven/tasks/TaskContext.java

@@ -37,6 +37,9 @@ public final class TaskContext {
     /** if we shall pass the -r flag to jsdoc. */
     private final boolean recursive;
 
+    /** if the jsdoc generator should tolerate errors (true), or fail on them (false). */
+    private final boolean lenient;
+
     /** if we shall pass the -p flag to jsdoc. */
     private final boolean includePrivate;
 
@@ -47,19 +50,20 @@ public final class TaskContext {
     /**
      * Private constructor.
      *
-     * @param sourceDir      the source dir.
-     * @param outputDir      the output dir.
-     * @param jsDocDir       the jsdoc dir.
-     * @param jsDocDir       the tutorials dir.
-     * @param configFile     the configuration file (i.e. conf.json).
-     * @param tempDir        the temp dir.
-     * @param debug          if debug mode should be used.
-     * @param recursive      if the jsdoc task should recursively look for jsfiles.
-     * @param includePrivate if private symbols should be included.
-     * @param log            The logger.
+     * @param sourceDir           the source dir.
+     * @param outputDir           the output dir.
+     * @param jsDocDir            the jsdoc dir.
+     * @param tutorialsDirectory  the tutorials dir.
+     * @param configFile          the configuration file (i.e. conf.json).
+     * @param tempDir             the temp dir.
+     * @param debug               if debug mode should be used.
+     * @param recursive           if the jsdoc task should recursively look for jsfiles.
+     * @param includePrivate      if private symbols should be included.
+     * @param lenient             if the generator should be lenient with errors.
+     * @param log                 The logger.
      */
     TaskContext(Collection<File> sourceDir, File outputDir, File jsDocDir, File tutorialsDirectory, File configFile,
-                File tempDir, boolean debug, boolean recursive, boolean includePrivate, Log log) {
+                File tempDir, boolean debug, boolean recursive, boolean includePrivate, boolean lenient, Log log) {
         this.sourceDir  = sourceDir;
         this.jsDocDir   = jsDocDir;
         this.outputDir  = outputDir;
@@ -69,6 +73,7 @@ public final class TaskContext {
         this.debug      = debug;
         this.recursive  = recursive;
         this.includePrivate = includePrivate;
+        this.lenient = lenient;
         this.log = log;
     }
 
@@ -153,6 +158,17 @@ public boolean isIncludePrivate() {
         return includePrivate;
     }
 
+    /**
+     * Should the generator tolerate errors (true) or fail on them (false).
+     *
+     * See: http://usejsdoc.org/about-commandline.html
+     *
+     * @return If so.
+     */
+    public boolean isLenient() {
+        return lenient;
+    }
+
     /**
      * The logger.
      *
@@ -185,6 +201,8 @@ public static class Builder {
 
         private boolean includePrivate = false;
 
+        private boolean lenient;
+
         private File tutorialsDirectory;
 
         private Log log;
@@ -261,6 +279,12 @@ public Builder withIncludePrivate(final boolean includePrivate) {
             return this;
         }
 
+        public Builder withLeniency(boolean lenient) {
+            this.lenient = lenient;
+
+            return this;
+        }
+
         public Builder withDirectoryRoots(final File[] directoryRoots) {
             if (directoryRoots != null) {
                 this.directoryRoots.addAll(Arrays.asList(directoryRoots));
@@ -307,7 +331,7 @@ public TaskContext build() {
             // this is getting a little out of hand...
             return new TaskContext(sourceRoots,
                     outputDirectory, jsDocDirectory, tutorialsDirectory, configFile,
-                    tempDirectory, debug, recursive, includePrivate, log);
+                    tempDirectory, debug, recursive, includePrivate, lenient, log);
         }
     }
 }

jsdoc3-maven-plugin/src/test/java/com/github/phasebash/jsdoc3/maven/tasks/CopyTaskTest.java

@@ -23,7 +23,7 @@ public void setUp() {
     @Test
     public void testCopyDirDoesntExist() {
         final File tempFile = new File(temporaryFolder.getRoot(), "rooty");
-        final TaskContext context = new TaskContext(null, null, null, null, null, tempFile, false, true, false, null);
+        final TaskContext context = new TaskContext(null, null, null, null, null, tempFile, false, true, false, true, null);
         copyTask.execute(context);
         Assert.assertTrue("jsdoc.zip should exist.", new File(tempFile, "jsdoc.zip").exists());
     }
@@ -32,15 +32,15 @@ public void testCopyDirDoesntExist() {
     public void testCopyDirExists() {
         final File tempFile = new File(temporaryFolder.getRoot(), "rooty");
         tempFile.mkdirs();
-        final TaskContext context = new TaskContext(null, null, null, null, null, tempFile, false, true, false, null);
+        final TaskContext context = new TaskContext(null, null, null, null, null, tempFile, false, true, false, false, null);
         copyTask.execute(context);
         Assert.assertTrue("jsdoc.zip should exist.", new File(tempFile, "jsdoc.zip").exists());
     }
 
     @Test
     public void testCopyFileSize() {
         final File tempFile = new File(temporaryFolder.getRoot(), "rooty");
-        final TaskContext context = new TaskContext(null, null, null, null, null, tempFile, false, true, false, null);
+        final TaskContext context = new TaskContext(null, null, null, null, null, tempFile, false, true, false, true, null);
         copyTask.execute(context);
         Assert.assertTrue("jsdoc.zip should exist.", new File(tempFile, "jsdoc.zip").exists());
 

jsdoc3-maven-plugin/src/test/java/com/github/phasebash/jsdoc3/maven/tasks/JsDocArgumentBuilderTest.java

@@ -16,8 +16,6 @@
 import org.junit.rules.TemporaryFolder;
 
 import java.io.File;
-import java.util.Arrays;
-import java.util.HashSet;
 import java.util.List;
 
 public class JsDocArgumentBuilderTest {
@@ -27,19 +25,23 @@ public class JsDocArgumentBuilderTest {
 
     private TaskContext minimumContext;
 
+    private TaskContext.Builder minimumBuilder;
+
     private JsDocArgumentBuilder builder;
-    
+
     private static final String JS_DOC_DIR_NAME = "jzdocz";
 
     @Before
     public void setUp() {
         builder = new JsDocArgumentBuilder();
 
-        minimumContext = new TaskContext.Builder()
+        minimumBuilder = new TaskContext.Builder()
                 .withDirectoryRoots(new File[] { temporaryFolder.newFolder("dir1") })
                 .withJsDocDirectory(temporaryFolder.newFolder(JS_DOC_DIR_NAME))
                 .withOutputDirectory(temporaryFolder.newFolder("output"))
-                .withTempDirectory(temporaryFolder.newFolder("temp")).build();
+                .withTempDirectory(temporaryFolder.newFolder("temp"));
+
+        minimumContext = minimumBuilder.build();
     }
 
     @Test
@@ -51,6 +53,26 @@ public void testMinimalContext() {
         assertModule(arguments);
         assertJsDocJs(arguments);
         assertDirName(arguments);
+
+        Assert.assertFalse(arguments.contains("-l"));
+    }
+
+    @Test
+    public void testLenientContext() {
+        TaskContext.Builder lenientBuilder = new TaskContext.Builder(minimumBuilder);
+        Assert.assertTrue(builder.build(lenientBuilder.withLeniency(true).build()).contains("-l"));
+    }
+
+    @Test
+    public void testContextWithConfig() {
+        TaskContext.Builder configBuilder = new TaskContext.Builder(minimumBuilder).withConfigFile(new File("config"));
+        Assert.assertTrue(builder.build(configBuilder.build()).contains("-c"));
+    }
+
+    @Test
+    public void testContextWithIncludePrivate() {
+        TaskContext.Builder configBuilder = new TaskContext.Builder(minimumBuilder).withIncludePrivate(true);
+        Assert.assertTrue(builder.build(configBuilder.build()).contains("-p"));
     }
 
     private void assertDirName(List<String> arguments) {