ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Erik Hatcher <>
Subject Re: ant xdocs! it ran!
Date Sat, 15 Feb 2003 10:18:59 GMT
On Friday, February 14, 2003, at 08:41  PM, Jesse Stockall wrote:
> On Wednesday, February 12, 2003, at 08:46 PM, Erik Hatcher wrote:
>> What do you folks think?   Where do we go from here with it?
> How is the optional vs required, and default values being handed for  
> attributes? Some tasks such as the VSS and Pvcs tasks have:
> "Attribute description; optional, default false."

> Others like CCMReconfigure have "Attribute description (default  
> false)."

Ah, now the fun begins!  :)

The toughest thing about this is the required/optional designations.   
Steve and I punted on this a little by just making the description of  
the attributes say "required" or what the default value is.  See this  
for an example on both attributes: 

It would be easy enough to tag the simple tasks with @ant.attribute  
require="true" (or we could shorten it to @ant.required even).  But it  
gets more complex than that.  Think about the <property> task.  Its so  
overloaded with location/value/file/refid/environment that you have to  
pick exactly one of them, but none of them are required by themselves.   
How would we designate this?

Its a non-trivial issue.

And given that tasks can implement validation their own way, with even  
default values being pretty loose and perhaps dynamic, we should opt  
for the simplest approaches to this.  I'm very open to suggestions on  
how we do this, although this could get real complicated real fast.   
For the sake of discussion, how would we denote what we see here:

So whether name is used or not there are two different sets of  
possibilities, and also a text description is being used, not just  
true/false/yes/no flags.  While it seems sort of nice that our current  
documentation is looser and more free-form, I'm not sure its necessary  
to retain that style completely.  Being more formal and rigid for a  
task reference seems fine to me.  I'm not proposing we lose  
information, but rather that it be noted in a different way.  Complex  
validation requirements for attributes perhaps should just be noted in  
the task long description, or in the examples where a task-specific  
table could be created.


> I assumed that the "Attribute description; optional, default false."  
> syntax would generate a column for required vs optional and another  
> column for the default value if there was one. Is this in the works?

It'll be in the works when we come up with a solution to how to  
designate this.  Its trivial to pull metadata out of tags and then put  
that as another column or two.  I'm just not sure how the best way is  
to do it.

> In your reply to Gus Heck today you mentioned that there is a facility  
> to pull in samples. All I could see for the javac task that you used  
> as an example is the html in the javadoc comments for the class. Could  
> you point me in the right direction, I'd like to play with this  
> facility.

There is some issue with the Gump runs not picking up the merge for  
some (very odd) reason, but if you run proposal/xdocs/build.xml using  
the docs-from-scratch target you'll get them pulled in.  I've attached  
a JPG of what it looks like locally for me (update: attachment didn't  
go through, so I've removed it and retrying - run locally and you'll  
see the examples pulled in for javac and a couple of others).  Here's  
how it works:

The proposal/xdocs/build.xml has this:

     <antdoclet destdir="${gen.dir}"

The mergedir points to a directory where templates will receive merged  
information and incorporate it inline to the generated artifacts.  The  
template (task_xml.xdt) lives in the  
lib/xdoclet-apache-module-1.2b2.jar has this:

   <XDtMerge:merge file="{0}.xml" generateMergedFile="false">
     <!-- no merge file present -->

The {0} is the fully qualified package name of the class being  
processed, turned into a file system path.  In proposal/xdocs/src there  
are a few sample XML files out there.  How we refer to sample files is  
up for discussion too, and whether they live alongside the source code  
or in a separate "samples" directory is of no consequence to this  


View raw message