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 4.0 VDL documentation
- Mojarra 4.1 VDL documentation
- PrimeFaces latest VDL documentation
- PrimeFaces Extensions latest VDL documentation
Installation
Just drop the Vdldoc 3.2 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.2</version>
</dependency>
There are so far two Maven plugins (maintained by others) available in order to automate Vdldoc during a Maven build:
Download
-
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 asjakarta.el.ValueExpression
. -
3.0 (19 Jul 2020) - library - sources - javadoc
Added support for new Jakarta EE 9'shttps://jakarta.ee/xml/ns/*
XML namespace in addition to oldhttp://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 and added support for new Java EE 7'shttp://xmlns.jcp.org/*
XML namespace in addition to oldhttp://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 definied in<managed-bean>
entries offaces-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 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.