Mojarra JSF generates this facelet format doc: https://javaserverfaces.dev.java.net/nonav/docs/2.0/pdldocs/facelets/index.html

Claims to use this to do so: https://taglibrarydoc.dev.java.net/

So this seems like a good place to start looking into this.

Here's a new version of the tool that should work with the new version of TLD files.
http://grepcode.com/snapshot/repo1.maven.org/maven2/taglibrarydoc/tlddoc/1.3

It looks like Mojarra's plan is to derive their TLD from their facelets.xml via xsl, and then use this new tool on the TLD to get the TLDDoc. We can simply generate both from our Meta classes, and then use this same TLDDoc tool.

Investigate the new JSF 2 TLD and Facelets taglib.xml file formats to see if they support documenting TagHandlers. Find the JSF 2 documentation for the JSTL c: tags, which are all TagHandlers and not components. See how they're documented.

In short, the new tag library schema contemplates documenting tag handlers that are not components.

I downloaded the 2.1.2 binary bundle from http://javaserverfaces.java.net/download.html and unzipped the file. First, I opened /docs/vdldocs/facelets/index.html inside the uncompressed file to confirm that the JSTL c: tags were documented, and indeed they were. The documentation pages for these tags looked just like the pages for all the other tags. Then I moved to the /lib folder inside this uncompressed folder. There, I renamed jsf-impl.jar to jsf-impl.zip and unzipped the file. From this point on, I will refer to file locations relative to this newly uncompressed folder.

/com/sun/faces/web-facelettaglibrary_2_0.xsd is the new facelet tag library schema
/com/sun/faces/metadata/taglib contains various xml files that follow this schema, one for each tag library.

For example...
/com/sun/faces/metadata/taglib/html_basic.taglib.xml
/com/sun/faces/metadata/taglib/jstl-core.taglib.xml
The only difference in the entries of these files is that in the first one, the <tag> elements contain a <component> child element, while in the second one, they have a <handler-class> child element.

The schema itself is very straight forward. It the defines a choice among various child elements to define the type of tag:
<xsd:choice>
<xsd:element name="handler-class" type="javaee:fully-qualified-classType"/>
<xsd:element name="behavior" type="javaee:facelet-taglib-tag-behaviorType"/>
<xsd:element name="component" type="javaee:facelet-taglib-tag-componentType"/>
<xsd:element name="converter" type="javaee:facelet-taglib-tag-converterType"/>
<xsd:element name="validator" type="javaee:facelet-taglib-tag-validatorType"/>
<xsd:element name="source" type="javaee:string"/>
</xsd:choice>
The rest of the tag metadata, like attributes and such, is identical in all cases.

I couldn't find the JSTL c: tags documented in a .tld file. I only found .tld files for the html basic components and the JSF core tags.

The namespace identifier for these .tld files is http://java.sun.com/xml/ns/javaee/web-jsptaglibrary_2_1.xsd . This schema is not included in the JSF binary bundle, but it can be accessed using the identifier as a URL.

I examined this schema, and there doesn't seem to be any reason why tag handlers couldn't be documented.

Committed (rev 24916) support for TagHandler Meta classes to produce TagHandler artifacts.

These were the only TagHandler classes found in our code:
/ajax/AjaxBehaviorHandler.java
/animation/AnimationBehaviorHandler.java
/collector/CollectorTagHandler.java
/export/DataExporterTagHandler.java
/filedownload/FileDownloadTagHandler.java

I had to remove the <handler-class> tag from the second <animation> tag. Basically, the AnimationBehaviorHandler is a BehaviorHandler, which takes a BehaviorConfig in its constructor. So when the <handler-class> is specified inside the <behavior>, everything is good. But when <handler-class> is specified directly in the <tag>, then that's expecting a TagHandler, which takes a TagConfig in its constructor, which causes an exception.

Also, should there be two <tag> sections for animation, or should that be folded into one?

<tag>
<tag-name>animation</tag-name>
<behavior>
<behavior-id>org.icefaces.ace.animation.Animation</behavior-id>
<handler-class>org.icefaces.ace.component.animation.AnimationBehaviorHandler</handler-class>
</behavior>
</tag>
<tag>
<tag-name>animation</tag-name>
<handler-class>org.icefaces.ace.component.animation.AnimationBehaviorHandler</handler-class>
<attribute>
<description>Something</description>
<name>to</name>
<required>false</required>
<type>java.lang.String</type>
</attribute>

I just fixed that at rev 24950. There will be only one <tag> entry for the animation behavior. We were creating this entry ad hoc. I just removed that code, and now the entry is being generated correctly (i.e. with the <behavior> element inside).

The hard-coded entries for animation in faces-config.xml were removed and now they are generated, based on the @TagHandler annotation. This applies all existing tag handlers, which at the moment only include <ace:animation> and <ace:ajax>.

A redundant version of the faces-config.xml entries must now be removed from the ace/resources/META-INF/faces-config.xml file.

did task above, committed at revision 26382