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:

NameDepends OnTypeDescription
downloadJSDocdownloadNodeDownloadNodeModuleTaskDownloads JSDoc in the project’s node_modules directory.
jsdocdownloadJSDocJSDocTaskGenerates 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 NameDefault Value
destinationDir

If the java plugin is applied: "${project.docsDir}/jsdoc"

Otherwise: "${project.buildDir}/jsdoc"

sourceDirsThe 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:

NameDepends OnTypeDescription
appJSDocdownloadJSDocJSDocTaskGenerates API documentation for the app’s JavaScript code.
downloadJSDocdownloadNodeDownloadNodeModuleTaskDownloads JSDoc in the app’s node_modules directory.
jarAppJSDocappJSDocJarAssembles 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 NameDefault Value
destinationDir${project.buildDir}/docs/jsdoc
sourceDirsThe 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 NameTypeDefault ValueDescription
subprojectsSet<Project>project.subprojectsThe subprojects to include in the JavaScript documentation of the app.

The same extension exposes the following methods:

MethodDescription
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 NameDefault Value
scriptFile"${downloadJSDoc.moduleDir}/jsdoc.js"

Task Properties

Property NameTypeDefault ValueDescription
configurationTextResourcenullThe JSDoc configuration file. It sets the --configure argument.
destinationDirFilenullThe directory where the JavaScript API documentation files are saved. It sets the --destination argument.
packageJsonFileFile"${project.projectDir}/package.json"The path to the project’s package file. It sets the --package argument.
sourceDirsFileCollection[]The directories that contains the files to process.
readmeFileFilenullThe path to the project’s README file. It sets the --readme argument.
tutorialsDirFilenullThe 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.

Was this article helpful?
0 out of 0 found this helpful