beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Hanson <stevelukehan...@gmail.com>
Subject New Tool for Doc'ing NetUI Tag Libraries
Date Thu, 10 Nov 2005 22:30:41 GMT
Hi all:

In the coming couple of weeks, I would like to change the way that the NetUI
JSP tags are doc'd.

Currently the NetUI tags are doc'd using a doclet (the "JSP Taglib Doclet")
developed by myself and Steve Traut. It's a nice tool, but it has drawbacks:
namely, (1) it has a dependency on XMLBeans and (2) it creates duplicated
javadoc content in the NetUI tag Java classes.

Please take a look at these options for a replacement doc tool. If you any
clear preferences, or other suggestions, please speak up.

thanks,
Steve Hanson

(1) Plain old javadoc

Sample doc:
http://beehive.apache.org/docs/1.0/apidocs/classref_netui/org/apache/beehive/netui/tags/html/Anchor.html

Drawbacks: Users have to translate Javadoc-isms into taglibrary-isms. For
example, they have to read the method "setName()" as the tag attribute
"name". Also, certain info important to tags is left out. For example,
whether an attribute is required or optional.

(2) tlddoc (Sun's tool available at https://taglibrarydoc.dev.java.net/)

Sample doc: http://struts.apache.org/struts-taglib/tlddoc/index.html

Tlddoc can be run against the Java source directly or against the TLD files.
The output looks nice, to me at least.

Open question: can we legally checkin the tlddoc.jar? Some people have said
"no". But I see other projects have checked in the jar:
http://cvs.sourceforge.net/viewcvs.py/myfaces/myfaces/lib/tlddoc.jar?rev=1.1&view=log

Giving the BSD license a quick skim, it seems ok to checkin the jar, but I
hesitate. Does anyone understand the BSD license well enough to answer this
question?

(3) Maven taglib plugin (available at http://maven-taglib.sourceforge.net/)
Sample doc:
http://struts.apache.org/struts-taglib/tagreference-struts-html.html
(I am not sure why Struts uses both tlddoc and Maven to doc the same
taglibs.)

This doc doesn't look as nice as the tlddoc, but I list it here as a
possibility.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message