View on GitHub

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:

Installation

Just drop the Vdldoc 3.0 JAR file 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>3.0</version>
</dependency>

There are so far two Maven plugins (maintained by others) available in order to automate Vdldoc during a Maven build:

Download

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 default 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> will be used as the taglib prefix. Make sure that you have supplied one. E.g.

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

Or if you are not on Facelets 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 definied 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-3.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 don't know how to relicense it without any potential law trouble. So we decided to keep it BSD.