ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jesse Stockall <>
Subject Re: ant xdocs! it ran!
Date Sat, 15 Feb 2003 15:18:55 GMT
On Saturday, February 15, 2003, at 05:18 AM, Erik Hatcher wrote:
> 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.
> Thoughts?

What about having 'attribute groups' for each task. Each attribute  
would have something like"optional" or"required". This would work well for simple  
tasks. For something like <property> the attributes could have  
something like this"group-name" and"group-no-name". An the top of the class there  
would be a tag called @ant.requires.all="required" and one called"group-name, group-no-name". To get it exactly  
like the current <property> documentation you would also need an  
optional tag called"One  
of these when using the name attribute"

Noting the validation requirements in the description could supplement  
the information in the table, but I really like being able to look at  
the table to determine the attribute requirements.

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

<!-- snip -->

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

Hmmm, I have run it locally, and I only get the html embedded in the  
javadocs. The output line for [antdoclet] says 'Generating output for  
'' using template file  

It doesn't show the merge file being used, should it?

Jesse Stockall -
CRYPTOCard Corp.

View raw message