Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
src
.lfrbuild-semantic-versioning
CHANGELOG.markdown
README.markdown
bnd.bnd
build.gradle

README.markdown

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.25"
	}

	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.

You can’t perform that action at this time.