JSDoc Gradle Plugin

The JSDoc Gradle plugin lets you run the JSDoc tool in order to generate documentation for your project’s JavaScript files.

The plugin has been successfully tested with Gradle 4.10.2.

Usage

To use the plugin, include it in your build script:

buildscript {
    dependencies {
        classpath group: "com.liferay", name: "com.liferay.gradle.plugins.jsdoc", version: "2.0.33"
    }

    repositories {
        maven {
            url "https://repository-cdn.liferay.com/nexus/content/groups/public"
        }
    }
}

There are two JSDoc Gradle plugins you can apply to your project:

• Apply the JSDoc Plugin to generate JavaScript documentation for your project:

  apply plugin: "com.liferay.jsdoc"
  

• Apply the App JSDoc Plugin in a parent project to generate the JavaScript documentation as a single, combined HTML document for an application that spans different subprojects, each one representing a different component of the same application:

  apply plugin: "com.liferay.app.jsdoc"
  

Both plugins automatically apply the com.liferay.node plugin.

JSDoc Plugin

The plugin adds two tasks to your project:

Name	Depends On	Type	Description
downloadJSDoc	downloadNode	DownloadNodeModuleTask	Downloads JSDoc in the project’s node_modules directory.
jsdoc	downloadJSDoc	JSDocTask	Generates API documentation for the project’s JavaScript code.

By default, the downloadJSDoc task downloads version 3.5.5 of the jsdoc package. If the project’s package.json file, however, already lists the jsdoc package in its dependencies or devDependencies, the downloadJSDoc task is disabled.

The jsdoc task is automatically configured with sensible defaults, depending on whether the java plugin is applied:

Property Name	Default Value
destinationDir	If the java plugin is applied: "${project.docsDir}/jsdoc" Otherwise: "${project.buildDir}/jsdoc"
sourceDirs	The directory META-INF/resources in the first resources directory of the main source set (by default, src/main/resources/META-INF/resources).

AppJSDoc Plugin

To use the App JSDoc plugin, it is required to apply the com.liferay.app.jsdoc plugin in a parent project (that is, a project that is a common ancestor of all the subprojects representing the various components of the app). It is also required to apply the com.liferay.jsdoc plugin to all the subprojects that contain JavaScript files.

The App JSDoc plugin adds three tasks to your project:

Name	Depends On	Type	Description
appJSDoc	downloadJSDoc	JSDocTask	Generates API documentation for the app’s JavaScript code.
downloadJSDoc	downloadNode	DownloadNodeModuleTask	Downloads JSDoc in the app’s node_modules directory.
jarAppJSDoc	appJSDoc	Jar	Assembles a JAR archive containing the JavaScript documentation files for this app.

By default, the downloadJSDoc task downloads version 3.5.5 of the jsdoc package. If the project’s package.json file, however, already lists the jsdoc package in its dependencies or devDependencies, the downloadJSDoc task is disabled.

The appJSDoc task is automatically configured with sensible defaults:

Property Name	Default Value
destinationDir	${project.buildDir}/docs/jsdoc
sourceDirs	The sum of all the jsdoc.sourceDirs values of the subprojects.

Project Extension

The App JSDoc plugin exposes the following properties through the extension named appJSDocConfiguration:

Property Name	Type	Default Value	Description
subprojects	Set<Project>	project.subprojects	The subprojects to include in the JavaScript documentation of the app.

The same extension exposes the following methods:

Method	Description
AppJSDocConfigurationExtension subprojects(Iterable<Project> subprojects)	Include additional projects in the JavaScript documentation of the app.
AppJSDocConfigurationExtension subprojects(Project... subprojects)	Include additional projects in the JavaScript documentation of the app.

Tasks

JSDocTask

Tasks of type JSDocTask extend ExecuteNodeScriptTask, so all its properties and methods, such as args, inheritProxy, and workingDir, are available.

They also have the following properties set by default:

Property Name	Default Value
scriptFile	"${downloadJSDoc.moduleDir}/jsdoc.js"

Task Properties

Property Name	Type	Default Value	Description
configuration	TextResource	null	The JSDoc configuration file. It sets the --configure argument.
destinationDir	File	null	The directory where the JavaScript API documentation files are saved. It sets the --destination argument.
packageJsonFile	File	"${project.projectDir}/package.json"	The path to the project’s package file. It sets the --package argument.
sourceDirs	FileCollection	[]	The directories that contains the files to process.
readmeFile	File	null	The path to the project’s README file. It sets the --readme argument.
tutorialsDir	File	null	The directory in which JSDoc should search for tutorials. It sets the --tutorials argument.

The properties of type File support any type that can be resolved by project.file.