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:
http://nagoya.apache.org/gump/javadoc/ant/proposal/xdocs/build/docs/ manual/control/condition.html
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?
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}"
excludedtags="@version,@author"
force="${xdoclet.force}"
mergedir="src">
...
</antdoclet>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 -->
</XDtMerge:merge>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.
Erik
