TLDDoc Builder Gradle Plugin

The TLDDoc Builder Gradle plugin lets you run the Tag Library Documentation Generator tool in order to generate documentation for the JSP Tag Library Descriptor (TLD) files in your project.

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.tlddoc.builder", version: "1.3.3"
    }

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

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

• Apply the TLDDoc Builder Plugin to generate tag library documentation for your project:

  apply plugin: "com.liferay.tlddoc.builder"
  

• Apply the App TLDDoc Builder Plugin in a parent project to generate the tag library 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.tlddoc.builder"
  

Since the plugin automatically resolves the Tag Library Documentation Generator library as a dependency, you must configure a repository that hosts the library and its transitive dependencies. The Liferay CDN repository hosts them all:

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

TLDDoc Builder Plugin

The plugin adds three tasks to your project:

Name	Depends On	Type	Description
copyTLDDocResources	-	Copy	Copies the tag library documentation resources from src/main/tlddoc to the destination directory of the tlddoc task.
tlddoc	copyTLDDocResources, validateTLD	TLDDocTask	Generates the tag library documentation.
validateTLD	-	ValidateSchemaTask	Validates the TLD files in the project.

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

Property Name	Default Value with the java plugin
destinationDir	${project.docsDir}/tlddoc
includes	["**/*.tld"]
source	project.sourceSets.main.resources.srcDirs

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

Property Name	Default Value
includes	If the java plugin is applied: ["**/*.tld"] Otherwise: []
source	If the java plugin is applied: project.sourceSets.main.resources.srcDirs Otherwise: null

By default, the tlddoc task generates the documentation for all the TLD files that are found in the resources directories of the main source set. The documentation files are saved in build/docs/tlddoc and include the files copied from src/main/tlddoc.

The copyTLDDocResources task lets you add references to images and other resources directly in the TLD files. For example, if the project includes an image called breadcrumb.png in the src/main/tlddoc/images directory, you can reference it in a TLD file contained in the src/main/resources directory:

<description>Hello World <![CDATA[<img src="../images/breadcrumb.png"]]></description>

App TLDDoc Builder Plugin

In order to use the App TLDDoc Builder plugin, it is required to apply the com.liferay.app.tlddoc.builder 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.tlddoc.builder plugin to all the subprojects that contain TLD files.

The App TLDDoc Builder plugin automatically applies the base plugin. It also adds three tasks to your project:

Name	Depends On	Type	Description
appTLDDoc	copyAppTLDDocResources, the validateTLD tasks of the subprojects	TLDDocTask	Generates tag library documentation for the app.
copyAppTLDDocResources	-	Copy	Copies the tag library documentation resources defined as inputs for the copyTDLDocResources tasks of the subprojects, aggregating them into the destination directory of the appTLDDoc task.
jarAppTLDDoc	appTLDDoc	Jar	Assembles a JAR archive containing the tag library documentation files for this app.

The appTLDDoc task is automatically configured with sensible defaults:

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

Project Extension

The App TLDDoc Builder plugin exposes the following properties through the extension named appTLDDocBuilder:

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

The same extension exposes the following methods:

Method	Description
AppTLDDocBuilderExtension subprojects(Iterable<Project> subprojects)	Include additional projects in the tag library documentation of the app.
AppTLDDocBuilderExtension subprojects(Project... subprojects)	Include additional projects in the tag library documentation of the app.

Tasks

TLDDocTask

Tasks of type TLDDocTask extend JavaExec, so all its properties and methods, such as args and maxHeapSize, are available. They also have the following properties set by default:

Property Name	Default Value
args	Tag Library Documentation Generator command line arguments
classpath	project.configurations.tlddoc
main	"com.sun.tlddoc.TLDDoc"
maxHeapSize	"256m"

The TLDDocTask class is also very similar to SourceTask, which means it provides a source property and lets you specify include and exclude patterns.

Task Properties

Property Name	Type	Default Value	Description
destinationDir	File	null	The directory where the tag library documentation files are saved.
excludes	Set<String>	[]	The TLD file patterns to exclude.
includes	Set<String>	[]	The TLD file patterns to include.
source	FileTree	[]	The TLD files to generate documentation for, after the include and exclude patterns have been applied.
xsltDir	File	null	The directory that contains the custom XSLT stylesheets used by the Tag Library Documentation Generator to produce the final documentation files. It sets the -xslt argument.

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

Task Methods

The methods available for TLDDocTask are exactly the same as the one defined in the SourceTask class.

ValidateSchemaTask

Tasks of type ValidateSchemaTask extend SourceTask, so all its properties and methods, such as include and exclude, are available.

Tasks of this type invoke the schemavalidate Ant task in order to validate XML files described by an XML schema.

Task Properties

Property Name	Type	Default Value	Description
dtdDisabled	boolean	false	Whether to disable DTD support.
fullChecking	boolean	true	Whether to enable full schema checking.
lenient	boolean	false	Whether to only check if the XML document is well-formed.
xmlParserClassName	String	null	The class name of the XML parser to use.
xmlParserClasspath	FileCollection	null	The classpath with the XML parser.

It is possible to use Closures and Callables as values for the String properties to defer evaluation until task execution.

Additional Configuration

There are additional configurations that can help you use the TLDDoc Builder.

Tag Library Documentation Generator Dependency

By default, the plugin creates a configuration called tlddoc and adds a dependency to the 1.3 version of the Tag Library Documentation Generator. It is possible to override this setting and use a specific version of the tool by manually adding a dependency to the tlddoc configuration:

dependencies {
    tlddoc group: "taglibrarydoc", name: "tlddoc", version: "1.3"
}