velocity-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gabriel Sidler <sid...@teamup.com>
Subject Re: documentation for Velocity template creators/updators
Date Tue, 10 Sep 2002 17:12:50 GMT
Joshua,
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

Joshua.Levy@reasoning.com 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 Foo.java, 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:   <mailto:velocity-user-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: <mailto:velocity-user-help@jakarta.apache.org>
> 
> .
> 
> 


-- 
--
Gabriel Sidler
Software Engineer, Eivycom GmbH, Zurich, Switzerland


--
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