Mailing-List: contact taglibs-dev-help@jakarta.apache.org; run by ezmlm
Sender: glenn@zathras.earthdome.org
Message-ID: <3A6EB423.1C9BE742@voyager.apg.more.net>
Date: Wed, 24 Jan 2001 04:53:23 -0600
From: Glenn Nielsen <glenn@voyager.apg.more.net>
MIME-Version: 1.0
To: taglibs-dev@jakarta.apache.org
Subject: Re: Best Practices: How to Document TagLibs
References: <AHECJODEJHEDHKHAGPFAEEHNCCAA.keytonw@bellsouth.net>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

"A. Keyton Weissinger" wrote:
> 
> Hello.
> 
> I would like to start a thread on best practices for taglib documentation.
> Questions for discussion:
> 
> 1) Who is taglib documentation for? I would suggest mostly for users as
> JavaDocs are for developers/extenders.

Agreed.  JavaDocs are for Java Programmers.  Tag Lib docs should be for
JSP Page authors.

> 2) What is the best mechanism out there. I like Ewan's and I like Scott's.
> Ewan's seems the most efficient in terms of developer time, but Scott's
> seems more flexible (or at least more easily flexible). I can see pros and
> cons either way. Any one have any strong opinions with constructive reasons
> as to why?

How a developer wants to generate documentation for a tag lib is up to them.
Tools which make it easier and standardize the user docs are a good idea.
The focus needs to be on providing good documentation for JSP authors who
are using the tag lib.

> 3) From the 1.2 spec, it looks like Scott's way is the wave of the future if
> either is (i.e TLD files become more comprehensive, allowing for more to be
> derivable from them). Along these lines has anyone begun playing with the
> ValidatorClass stuff and how this fits in with concept of documenting from
> the tld?
> 

Providing documenation in the TLD will be important so that web publishing
tools which provide support for JSP tag libs can provide context sensitve
help.

To this point I haven't done much more than browse the Servlet 2.3 and
JSP 1.2 draft specs.  From looking at the spec, the ValidatorClass will
be invoked at translation time so you can do additional JSP page validation
specific to your tag lib.  It seems pretty wide open, any documenation
related to translation time validation would be specific to the tag lib.
Kind of hard to standardize it.  I have considered implementing the isValid()
method of the TagExtraInfo in the JSP 1.1 spec for cases where you have multiple 
attributes that can be mutually exclusive at translation time, i.e. the user 
can use attr1 or attr2, but not both.

Regards,

Glenn


----------------------------------------------------------------------
Glenn Nielsen             glenn@more.net | /* Spelin donut madder    |
MOREnet System Programming               |  * if iz ina coment.      |
Missouri Research and Education Network  |  */                       |
----------------------------------------------------------------------