ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jesse Stockall <je...@cryptocard.com>
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:
>
> http://ant.apache.org/manual/CoreTasks/property.html
>
> 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 @ant.requirement.group="optional" or  
@ant.requirement.group="required". This would work well for simple  
tasks. For something like <property> the attributes could have  
something like this @ant.requirement.group="group-name" and  
@ant.requirement.group="group-no-name". An the top of the class there  
would be a tag called @ant.requires.all="required" and one called  
@ant.requires.one.of="group-name, group-no-name". To get it exactly  
like the current <property> documentation you would also need an  
optional tag called @ant.requirement.group.description.group-name="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  
'org.apache.tools.ant.taskdefs.Javac' using template file  
'jar:file:/home/jesse/source/ant/proposal/xdocs/lib/xdoclet-apache- 
module-1.2b2.jar!/xdoclet/modules/apache/ant/resources/task_xml.xdt'.'

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

Jesse Stockall - jesse@cryptocard.com
CRYPTOCard Corp.


Mime
View raw message