Vdldoc

Facelets .taglib.xml documentation generator.

What is Vdldoc?

Vdldoc is a forked and rewritten version of old JSP TLDdoc Generator as previously available at http://taglibrarydoc.dev.java.net (which is nowhere available right now). Vdldoc has near-complete support for Facelets *.taglib.xml files. The generated documentation has Java 8 javadoc look'n'feel.

As a preview, you can check the following online examples:

• OmniFaces: 5.1 VDL documentation
• Mojarra: 4.1 VDL documentation
• PrimeFaces: latest VDL documentation
• PrimeFaces Extensions: latest VDL documentation

Installation

Just drop the Vdldoc 4.0 JAR file into the classpath. If you are using Maven, you can include the following dependency in your pom.xml:

<dependency>
    <groupId>org.omnifaces</groupId>
    <artifactId>vdldoc</artifactId>
    <version>4.0</version>
</dependency>

There is also a Maven plugin (maintained by others) available in order to automate Vdldoc during a Maven build:

• https://github.com/matinh/vdldoc-maven-plugin

It's also used by OmniFaces and PrimeFaces.

Download

• 4.0 (10 Mar 2026) - library - sources - javadoc
  • Minimum Java SE runtime requirement is now Java 17 instead of Java 1.6 (!!).
  • Added support for new Jakarta EE 10's jakarta.faces.composite XML namespace in addition to old http://xmlns.jcp.org/jsf/composite XML namespace.
  • The -doctitle defaults now to the final value of -windowtitle instead of to its default.
• 3.2 (21 Jun 2024) - library - sources - javadoc
  • Empty taglibs (e.g. Jakarta Faces Passthrough) are now allowed.
  • Tag summaries and attributes are now ordered by name.
• 3.1 (6 Dec 2020) - library - sources - javadoc
  • The "type" javax.el.ValueExpression will now show up as jakarta.el.ValueExpression.
• 3.0 (19 Jul 2020) - library - sources - javadoc
  • Added support for new Jakarta EE 9's https://jakarta.ee/xml/ns/* XML namespace in addition to old http://xmlns.jcp.org/* XML namespace.
• 2.1 (12 Sep 2015) - library - sources - javadoc
  • Added option to hide "Generated by Vdldoc" footer.
  • Added option to explicitly set CSS location (allowing overriding default CSS).
  • Added support for Facelets 2.2 <short-name> tag.
• 2.0 (24 Nov 2014) - library - sources - javadoc
  • Changed look'n'feel to Java 8 javadoc.
  • Added support for new Java EE 7's http://xmlns.jcp.org/* XML namespace in addition to old http://java.sun.com/* XML namespace.
• 1.2 (30 Apr 2014) - library - sources - javadoc
  • Added support for composite components available by <composite-library-name> entry of .taglib.xml files.
• 1.1 (10 Sep 2013) - library - sources - javadoc
  • Added support for managed beans defined in <managed-bean> entries of faces-config.xml file.
• 1.0 (9 March 2012) - library - sources
  • Initial release, just forked TLDdoc and altered for Facelets .taglib.xml files with Java 7 javadoc look'n'feel, with support for <tag> and <function> entries of .taglib.xml files.

Usage

Much like old TLDdoc usage, once the jar is in runtime classpath, run it as follows:

VdldocGenerator generator = new VdldocGenerator();
generator.setWindowTitle("Browser window title"); // Else default will be used.
generator.setDocTitle("Documentation title"); // Else window title will be used.
generator.setOutputDirectory(new File("/path/to/vdldoc")); // Else ./vdldoc will be used.
generator.setCssLocation("/uri/to/style.css"); // Optional (overrides default CSS).
generator.setFacesConfig(new File("/path/to/faces-config.xml")); // Optional.
generator.setAttributes(new File("/path/to/cc-attributes.properties")); // Optional.
generator.addTaglib(new File("/path/to/foo.taglib.xml"));
generator.addTaglib(new File("/path/to/bar.taglib.xml"));
// ...
generator.generate();

The <facelet-taglib><short-name> (introduced in JSF 2.2) will be used as the taglib prefix. Make sure that you have supplied one. E.g.

<facelet-taglib>
    <description>OmniFaces UI components.</description>
    <namespace>omnifaces</namespace>
    <short-name>o</short-name>
    ...
</facelet-taglib>

Or if you are not on JSF 2.2 yet, you can supply <facelet-taglib id> instead. E.g.

<facelet-taglib id="o">
    <description>OmniFaces UI components.</description>
    <namespace>http://omnifaces.org/ui</namespace>
    ...
</facelet-taglib>

Otherwise, it will default to the base filename without the .taglib.xml extension.

Note: MyFaces has a known parsing issue when using <description> in the <facelet-taglib> as demonstrated above. This has been fixed for MyFaces 2.0.14 and 2.1.8. This problem is completely unrelated to Vdldoc.

As to the cc-attributes.properties file (the file name is by the way fully free to your choice, as long as it's a valid Java .properties file), this is specifically for implied composite component attributes which are not defined via <cc:attribute>. Therein you can define the display name, description, required and type columns of the attributes in the following syntax:

# id
id.displayName=id
id.description=The identifier of the component.
id.required=false
id.type=java.lang.String
# rendered
rendered.displayName=rendered
rendered.description=Boolean flag indicating whether or not this component is to be rendered during the RENDER_RESPONSE phase of the JSF lifecycle.  The default value is true.
rendered.required=false
rendered.type=java.lang.Boolean

If this file is not specified, then the above specified defaults will be used.

CLI

The vdldoc.jar can be also run in the command line like so:

java -jar vdldoc-4.0.jar foo.taglib.xml bar.taglib.xml

The files will by default be generated into a new /vdldoc folder in the working directory. The usage options are laid out below:

------------------------------------------------------------------------------
                        VDL Documentation Generator
Usage:
               vdldoc [options] taglib1 [taglib2 [taglib3 ...]]
options:
  -help                  Displays this help message.
  -d <directory>         Destination directory for output files.
                         This defaults to new dir called 'vdldoc'.
  -windowtitle <text>    Browser window title. This defaults to
                         VDL Documentation Generator - Generated Documentation
  -doctitle <html-code>  Documentation title for the VDL index page.
                         This defaults to the same as window title.
  -css <uri>             URI of the CSS file. This defaults to internal CSS.
  -facesconfig <path>    Path to the faces-config.xml file.
  -attr <path>           Path to properties file containing descriptions for
                         implied attributes of composite components, such as
                         'id', 'rendered', etc.
  -f                     Hide 'Output generated by Vdldoc' footer.
  -q                     Quiet Mode, i.e. disable logging.
taglib1 [taglib2 [taglib3 ...]]: Space separated paths to .taglib.xml files.
    NOTE: if an argument or file path contains by itself spaces, quote it.
------------------------------------------------------------------------------

License

Vdldoc has BSD license, because the original TLDDoc was also BSD. Note that we would personally like it to be Apache 2.0 license instead, but we didn't know how to relicense it without any potential law trouble. So we decided to keep it BSD.