You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beehive.apache.org by Steve Hanson <st...@gmail.com> on 2005/11/10 23:30:41 UTC
New Tool for Doc'ing NetUI Tag Libraries
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.
Re: New Tool for Doc'ing NetUI Tag Libraries
Posted by Steve Hanson <st...@gmail.com>.
No problem Eddie, I will hold off for now.
In case you find it useful, here is the text of my exchange with Mark Roth (
markroth8@gmail.com), the lead of tlddoc:
Hi Steve,
Nice to hear from you - great work on Beehive!
On Fri, 2005-12-02 at 14:01 -0800, Steve Hanson wrote:
> Hi Mark:
>
> I am looking around for tools to document the taglibraries in Apache
> Beehive (http://beehive.apache.org/).
>
> tlddoc is currently my favorite choice, but I have a question:
Awesome! Glad to hear taglibrarydoc is useful to you and you're
considering using it for Beehive!
> Is it ok (according to the BSD license) to checkin tlddoc.jar to the
> Beehive source tree? We would not be distributing tlddoc.jar with any
> Beehive release distributions, but it would be part of the source
> tree.
Absolutely, so long as you retain the copyright notice. The BSD license
is one of the most liberal licenses and that's why I chose it. You can
see the entirety of the license here:
http://www.opensource.org/licenses/bsd-license.html
The relevant portion is:
"Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution."
It's strange how these things work. I started the project while I was
working at Sun and now I've moved on to another position but Sun retains
the copyright. So basically you can commit the JAR but you just have to
include a file that says that taglibrarydoc is licensed under BSD and is
copyrighted by Sun Microsystems (look at one of the source files for the
full copyright message).
FYI, if I find some time this weekend I'll be releasing a new version
with support for the new features in the JSP 2.1 specification.
Thanks for your interest, and best of luck with Beehive!
- Mark
On 12/8/05, Eddie O'Neil <ek...@gmail.com> wrote:
>
> Steve--
>
> Give me an opportunity to clear this with the Apache legal folks
> before we commit this to the SVN tree. Will be easier to keep it out
> at first than take it out later.
>
> Will let you know what I hear back.
>
> Thanks!
>
> Eddie
>
>
> On 12/8/05, Steve Hanson <st...@gmail.com> wrote:
> > 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 <st...@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.
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> >
> >
>
Re: New Tool for Doc'ing NetUI Tag Libraries
Posted by Eddie O'Neil <ek...@gmail.com>.
Steve--
Give me an opportunity to clear this with the Apache legal folks
before we commit this to the SVN tree. Will be easier to keep it out
at first than take it out later.
Will let you know what I hear back.
Thanks!
Eddie
On 12/8/05, Steve Hanson <st...@gmail.com> wrote:
> 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 <st...@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.
> >
> >
> >
> >
> >
> >
> >
>
>
Re: New Tool for Doc'ing NetUI Tag Libraries
Posted by Steve Hanson <st...@gmail.com>.
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 <st...@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.
>
>
>
>
>
>
>