You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ant.apache.org by Erik Hatcher <ja...@ehatchersolutions.com> on 2003/02/13 02:46:46 UTC
ant xdocs! it ran!
I have not checked in a couple of days, and hadn't even noticed that
the nags weren't coming, and I haven't a clue what changed to fix it,
but my prototype Ant docs (thanks to Bill's great DVSL work too!) are
now being generated by Gump. At the end of the build you can see how
many categories and task docs were generated:
http://nagoya.apache.org/~rubys/gump/ant-xdocs-proposal.html
And now for the docs themselves:
http://nagoya.apache.org/gump/javadoc/ant/proposal/xdocs/build/docs/
manual/index.html
The first page is a quick and dirty hack to generate an index of
everything generated and hyperlink it all from one place, so obviously
that needs to be revamped, but look specifically at the task docs
themselves.
What do you folks think? Where do we go from here with it?
Erik
Re: ant xdocs! it ran!
Posted by Jesse Stockall <je...@cryptocard.com>.
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)."
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?
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.
All in all, it looks pretty good.
Jesse Stockall - jesse@cryptocard.com
CRYPTOCard Corp.
Re: ant xdocs! it ran!
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
On Saturday, February 15, 2003, at 08:48 PM, Jesse Stockall wrote:
> The search pattern for the merge file looks for the exact name of the
> task. All the task names are all capitalized, but the names of the
> merge files were in lowercase. Mac OS X's file system isn't
> case-sensitive so like Windows the files would be found. I changed the
> case on Linux and now all is well.
Nice find! I've corrected them.... having to rename the condition.xml
altogether. Perhaps a more custom merge filename needs to be used
besides the task class name - food for thought.
Tomorrow the Gump run should have <tar>, <javac>, <javadoc>, and
<condition> documented with examples.
Erik
Re: ant xdocs! it ran!
Posted by Jesse Stockall <je...@cryptocard.com>.
On Saturday, February 15, 2003, at 04:18 PM, Erik Hatcher wrote:
> On Saturday, February 15, 2003, at 11:57 AM, Jesse Stockall wrote:
>> Now the plot thickens... The merges work fine on Mac OSX, but fail
>> (no errors) on Linux with Java 1.3.1 and 1.4. Maybe I'm running into
>> the same problems as Gump.
>
> Strange. I'm on Mac OS X, so maybe thats why I see success. This is
> a very strange thing. I'll dig on this too.
D'oh!
The search pattern for the merge file looks for the exact name of the
task. All the task names are all capitalized, but the names of the
merge files were in lowercase. Mac OS X's file system isn't
case-sensitive so like Windows the files would be found. I changed the
case on Linux and now all is well.
Jesse Stockall - jesse@cryptocard.com
CRYPTOCard Corp.
Re: ant xdocs! it ran!
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
On Saturday, February 15, 2003, at 11:57 AM, Jesse Stockall wrote:
> Now the plot thickens... The merges work fine on Mac OSX, but fail (no
> errors) on Linux with Java 1.3.1 and 1.4. Maybe I'm running into the
> same problems as Gump.
Strange. I'm on Mac OS X, so maybe thats why I see success. This is a
very strange thing. I'll dig on this too.
Erik
Re: ant xdocs! it ran!
Posted by Jesse Stockall <je...@cryptocard.com>.
On Saturday, February 15, 2003, at 10:18 AM, Jesse Stockall wrote:
>
>> 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:
>
> 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?
Now the plot thickens... The merges work fine on Mac OSX, but fail (no
errors) on Linux with Java 1.3.1 and 1.4. Maybe I'm running into the
same problems as Gump.
I'll dig a little deeper and post what I find.
Jesse Stockall - jesse@cryptocard.com
CRYPTOCard Corp.
Re: ant xdocs! it ran!
Posted by Jesse Stockall <je...@cryptocard.com>.
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.
Re: ant xdocs! it ran!
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
On Friday, February 14, 2003, at 08:41 PM, Jesse Stockall wrote:
> 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
Re: ant xdocs! it ran!
Posted by Jesse Stockall <je...@cryptocard.com>.
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)."
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?
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.
All in all, it looks pretty good.
Jesse Stockall - jesse@cryptocard.com
CRYPTOCard Corp.
Re: ant xdocs! it ran!
Posted by Diane Holt <ho...@yahoo.com>.
--- Erik Hatcher <ja...@ehatchersolutions.com> wrote:
> What do you folks think? Where do we go from here with it?
Looks good to me. Nice work.
Diane
(Hope I didn't shock too many people by actually having time to reply :)
=====
(holtdl@yahoo.com)
__________________________________________________
Do you Yahoo!?
Yahoo! Shopping - Send Flowers for Valentine's Day
http://shopping.yahoo.com