velocity-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gabriel Sidler <>
Subject Re: documentation for Velocity template creators/updators
Date Tue, 10 Sep 2002 17:12:50 GMT
the fundamental problem with using Javadoc for Velocity
context documentation is that Javadoc was designed to document
classes while we need to document object instances. An example:
A context may contain several lists of type ArrayList.
What we need to document are instance names, specific purpose
and type (class) of each object. JavaDoc is only a partial
answer for this.

Gabe wrote:

> Someone wrote:
>>>One problem with Velocity is documentation. Of course you 
>>>can generate JavaDocs out of your business logic classes. 
>>>But how can  you tell a Web Designer, which objects are 
>>>available where (in which  context). 
> Someone else replied:
>>This a very good point and is 100% consistent with my own 
>>experience. The difficulty to communicate the content of the 
>>Velocity context among software developers and designers is 
>>the biggest practical difficulty in using Velocity, IMHO.
> 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, you would have new tags, maybe like this:
>     @velocityConextVarible myFoo
>     @velocityInfo This object is used for ....
> 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.
> If you work on this, please tell me, so we don't duplicate work.
> I might work on it in the future, if I get time.
> Joshua
> --
> To unsubscribe, e-mail:   <>
> For additional commands, e-mail: <>
> .

Gabriel Sidler
Software Engineer, Eivycom GmbH, Zurich, Switzerland

To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message