beehive-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steve Hanson <stevelukehan...@gmail.com>
Subject Re: New Tool for Doc'ing NetUI Tag Libraries
Date Thu, 08 Dec 2005 18:52:12 GMT
An update on this issue.

I have talked to the devs at tlddoc and they have assured me that its ok to
checkin the tlddoc.jar into the source tree (provided we include a copy of
their copyright notice).

So, unless anyone objects, I will start to implement option (2) below.

On 11/10/05, Steve Hanson <stevelukehanson@gmail.com> wrote:
>
> 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/)<https://taglibrarydoc.dev.java.net/%29>
>
> 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