velocity-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bill Burton <bi...@progress.com>
Subject Re: documentation for Velocity template creators/updators
Date Thu, 12 Sep 2002 00:37:32 GMT
Hello,

Joshua.Levy@reasoning.com wrote:

#snip()

> I have the following idea to help solve this problem, but I
> don't have time to implement it right now.  Sorry :-(
> 
> The JavaDocs system is highly configurable.  You can create
> doclets which have specialized tags, and custom HTML generation
> based on those tags.  My suggestion is to create a doclet
> specialized to creating documentation for web designers using
> Velocity.  For example, if you have something like this:
>     velocityContext.put("myFoo", new Foo()) ;
> In Foo.java, you would have new tags, maybe like this:
>     @velocityConextVarible myFoo
>     @velocityInfo This object is used for ....

There are a couple of options I'm aware of.
  http://vdoclet.sourceforge.net/
  http://xdoclet.sourceforge.net/

You can read about the differences between these two packages at
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/vdoclet/vdoclet/doc/XDoclet-comparison.txt?rev=1.2&content-type=text/vnd.viewcvs-markup.

However, XDoclet and possibly vDoclet (if I understand it correctly),
generate completely separate output derived from the actual classes.  This
is fine for generating HTML or other API documentation for classes and
Beans put into the context but doesn't take into account the relationship
between the context name and the documented class nor does it take into
account chained contexts.

It would be possible to generate a page using tags such as those you
propose above using x/vDoclet that links the Velocity context name to the
correct API javadoc.  However, this won't work for cases where classes are
added to the context dynamically such as with the VelocityViewServlet
Toolbox.  

What I envision is more along the lines of others who've suggested putting
the context in the context and then iterating over it at runtime.  For web
applications, specifying an optional query string parameter could dump out
context documentation for that page based on whatever is in the context.

The missing pieces are:
1.  How do you attach a description to the context name?
    Maybe the description of the context could be passed at the 
    same time it's being set:
        velocityContext.put("myFoo", new Foo(),
            "This object is used for ...");

    Along the same line, The Toolbox of the VelocityViewServlet 
    could support a <description> element for any tools that are 
    added to the context.  

    If no description is specified, then the description should 
    be pulled from the javadoc short class description
    (first sentence).  Of course, this would require preprocessing
    all classes put into the context with x/vDoclet to generate 
    something such as a template that could make that info 
    available at runtime.

2.  How do you associate the context name with the URL for the API
javadoc?
    Maybe this would work by simply getting the class associated with the
context item and then generating a link to whereever the API javadoc
resides?  The base URL of the javadoc could be configured in some manner
so the template wouldn't require alterations to work.

> and then the methods visible to Velocity (such as getName) would
> have tags too, also focused on web designers.  The Java code which
> created the HTML documentation would print this stuff under name,
> not getName, because that is how a web designer would use it.

Special javadoc tags for classes put into the context shouldn't be needed
as the javadoc short description (first sentence) or long description
should suffice.  Many classes or Beans put into the context aren't
Velocity specific nor do they need to be.

Hope this helps,
-Bill

--
To unsubscribe, e-mail:   <mailto:velocity-user-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:velocity-user-help@jakarta.apache.org>


Mime
View raw message