My take on this is hard-nosed. Until we figure out a way to designate the required/optional distinction, in **all** its complexity, I cannot consider this an improvement whatever other virtues it may bring to the table. That simple column is the most useful thing to me about the ant documentation. I consult it whenever I go to write a build.xml that uses a task with which I am unfamiliar.
These are certainly reasonable and soundly based comments on this.
Again, I'm not at all proposing we lose information, but rather re-think how that information is generated a bit. More below...
I know it isn't easy. A is required unless B, C and D or E is specified. Not fun. But necessary to any automated solution.
I think we should follow the "do not repeat yourself" and "one and only one representation" of validation rules as best we can in this situation. Here are a few invariants that we have to work within:
- Tasks can implement very complex and even dynamic validation rules that are well out of reach of any type of codification except within Java code itself.
- Its already the case that keeping the current static HTML and the tasks in sync is problematic.
- The look and feel of the current documentation is not flexible.
- Tools cannot work with Ant except via introspection or by humans coding things manually.
Back to the original point of do not repeat ourselves... if we try to invent some way of codifying such validation rules in @tags we'll end up with the same out of sync issue. I'd rather us err on the side of just using the English language (or perhaps localize it all somehow) to define these loose things. This duplicates the validation rules a little too, still, because they'll be in Java code and also in a text description. These two will be in very close proximity though.
It would be sweeter if such validation constraints could be spelled out in @tags and those would be taken into consideration by the engine rather than having to code them ourselves. If we mark an attribute as @ant.attribute required="true" then we would not need to code in execute() to throw a BuildException if its not specified. This is asking a little too much at this time, so lets stick with trying to document things rather than changing the core :)
That being said, there is perhaps some happy medium with the "group" concept that Jesse mentioned and having text descriptions of the validation information. Certainly there are many attributes that are simply required or not and we could tighten it up and specify those rigidly too.
I think with some work we can probably get a good solution to make us all happy! I'll mull over everyones comments in the next couple of weeks and see what I can come up with.
Here's a random thought of dubious utility (especially since I have no idea how you're doing this) - isn't this problem similar to designing a DTD?
Except a DTD is much more limited in its rules than an Ant task could be. This would be much easier if the rules were as easy to follow as a DTD :)
This is why <antstructure> is mostly useless :)) Is it possible to spell out DTD rules for <property> that accurately reflects all its complexity?
Erik
