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 - [EMAIL PROTECTED] CRYPTOCard Corp.
