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 2002/03/03 03:27:56 UTC
XDoclet status update
I've enhanced the proposal/xdocs a bit to detect Ant tasks a lot better. It
climbs the hierarchy looking for a parent class with an execute() method
(except if it hits org.apache.tools.ant.Task it quits and doesn't count that
as a task).
I'm using the generation of defaults.properties as the "litmus test" to how
good the generation is working, and it just about matches our currently hand
maintained defaults.properties. Here are the exceptions:
XDoclet generates these extras:
ccmcheck=org.apache.tools.ant.taskdefs.optional.ccm.CCMCheck (any reason
not to make this abstract?)
iplanetejbc=org.apache.tools.ant.taskdefs.optional.ejb.IPlanetEjbc (this
couldn't really be used by a task because of the exceptions its execute
method throws, right? Or does that matter?)
mail=org.apache.tools.ant.taskdefs.SendEmail (it also generates the
correct mapping to EmailTask, perhaps need an 'ignore' flag?)
p4delete=org.apache.tools.ant.taskdefs.optional.perforce.P4Delete
p4reopen=org.apache.tools.ant.taskdefs.optional.perforce.P4Reopen
p4revert=org.apache.tools.ant.taskdefs.optional.perforce.P4Revert (these
are really tasks, but we have no mappings to them - why not?)
vajload=org.apache.tools.ant.taskdefs.optional.ide.VAJLoad
vajloadprojects=org.apache.tools.ant.taskdefs.optional.ide.VAJLoadProjects
(both are the same, essentially. Can we deprecate VAJLoadProjects?)
xalan1executor=org.apache.tools.ant.taskdefs.optional.junit.Xalan1Executor
xalan2executor=org.apache.tools.ant.taskdefs.optional.junit.Xalan2Executor
(Currently these look and smell like tasks, but their execute method throws
Exception - does that take them out of the running to really be tasks?)
XDoclet omits these:
copydir=org.apache.tools.ant.taskdefs.Copydir
copyfile=org.apache.tools.ant.taskdefs.Copyfile
deltree=org.apache.tools.ant.taskdefs.Deltree
javadoc2=org.apache.tools.ant.taskdefs.Javadoc
mimemail=org.apache.tools.ant.taskdefs.optional.net.MimeMail
rename=org.apache.tools.ant.taskdefs.Rename
renameext=org.apache.tools.ant.taskdefs.optional.RenameExtensions (all
of these are @deprecated)
unjar=org.apache.tools.ant.taskdefs.Expand
unwar=org.apache.tools.ant.taskdefs.Expand (several mappings to the same
class - need to handle this situation with XDoclet - shouldn't be a problem)
vajload=org.apache.tools.ant.taskdefs.optional.ide.VAJLoadProjects (need
to resolve issue from above)
I can easily bring the deprecated classes back to life, I just thought for
grins that I'd let it ignore them for now. I don't want to start a big
"deprecation" discussion again, and certainly removing deprecated classes
from the mappings file breaks backwards compatibility, so we'll have to
re-enable for the real thing.
Overall, it looks like its right on track with only a few minor issues.
Here are a few issues/ideas:
- Can a class with a method 'void execute() throws Exception' be a task?
- It seems that we have a few exceptions that will require an 'ant.task
ignore="true"' kinda thing so that it gets skipped over for processing even
though it could really be used as a task. Thoughts?
- There are several tasks that point to Expand, and right now there are
additional 'name="..."' in the class, but the template is not coded such
that it picks that up when building defaults.properties. This should be an
easy thing to add. But how would multiple names play out in the XML created
for a task? Should it create multiple XML files? Or just note the multiple
names as aliases in one XML file somehow?
- Categorization - should we restrict a task to a single category? Or allow
it to be in multiple? Or do we need a few different "bucket" types to drop
tasks into? I've been thinking we should have a "vendor" bucket so that we
could create groupings in documentation for all Weblogic tasks (wljspc,
wlrun, wlstop) for example. There are lots of ways we could go with this!
So start the brainstorming, and let me know.
Erik
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XDoclet status update [PATCH] attributes; merge points
Posted by Peter Donald <pe...@apache.org>.
On Sun, 3 Mar 2002 18:17, Bill Burton wrote:
> Hello,
>
> But wait! There's more!
Carving knives? Forks? Plates even?
> For those who would like to see the what documentation looks like without
> building it yourself, I've attached the file ant-xdocs.zip which contains
> a small but representative sample of task documentation in its current
> state.
ooer - that looks fantastic compared to our current docs ;)
--
Cheers,
Pete
*--------------------------------*
| Every rule has an exception, |
| except the rule of exceptions. |
*--------------------------------*
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XDoclet status update [PATCH] attributes; merge points
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
----- Original Message -----
From: "Bill Burton" <bi...@progress.com>
> I've made a number of enhancements to proposal/xdocs in the attached
> patch:
Bill, you rock! This is fantastic. The pushClass stuff is something I
hadn't tried, so you've now exceeded my XDoclet know-how :) Very cool.
> * Attributes listings are now generated by XDoclet for nested elements.
> Right now, there's no distiction between shared types or locally defined
> ones via inner classes so everything is output. This means it's somewhat
> verbose but also rather complete.
Yeah, but what about their nested elements?! :))
The question is how far do we want to go, and can XDoclet achieve that kind
of recursion currently?
I'm about to add in the datatypes defaults.properties generation also - so
I'll be creating some helper tags for those.
> * Implemented an XDoclet merge point so part of the documentation can now
> reside in an XML file in a package-relative directory to the .java
> source. This external XML file is merged into the generated XML by
> XDoclet. The stylesheet looks for <description> element and if found uses
> that instead of the javadoc class description. Examples and other content
> can be appended to the end just by putting them within a <section> tags
> just like the Jakarta docs.
So you've got a process that can take the current task HTML docs and convert
them to this?
We are getting so much closer to having those HTML docs be obsolete!
Lets start putting together a to-do list of what it will take to get us
there: (here are a few starters - I'll add this to the Ant 1.5 to-do list
I'll make a stab at later today)
- Wiser dealing with built-in datatpyes (no need to list their
attributes - just hyperlink to their own docs)
- Create the XML files for the datatypes
- Task categorization work, determine the desired groupings
- Have defaults.properties capable of generating multiple mappings for
the same task if multiple 'name' attributes
- Have class-level ignore="true" facility
> * Cleaned up the stylesheet so it formats the HTML in a much more readable
> manner. Added some HTML comments to it's easy to know what you're looking
> at.
It looks very nice.
Erik
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XDoclet status update [PATCH] attributes; merge points
Posted by Bill Burton <bi...@progress.com>.
Hello,
But wait! There's more!
I've made a number of enhancements to proposal/xdocs in the attached
patch:
* Attributes listings are now generated by XDoclet for nested elements.
Right now, there's no distiction between shared types or locally defined
ones via inner classes so everything is output. This means it's somewhat
verbose but also rather complete.
* Implemented an XDoclet merge point so part of the documentation can now
reside in an XML file in a package-relative directory to the .java
source. This external XML file is merged into the generated XML by
XDoclet. The stylesheet looks for <description> element and if found uses
that instead of the javadoc class description. Examples and other content
can be appended to the end just by putting them within a <section> tags
just like the Jakarta docs.
* Cleaned up the stylesheet so it formats the HTML in a much more readable
manner. Added some HTML comments to it's easy to know what you're looking
at.
* The stylesheet now pulls project info from the
xdocs/stylesheets/project.xml just like Anakia. This is used to determine
how to output the new logo. The URL to the logo is relative to the
location of the docs directory.
For those who would like to see the what documentation looks like without
building it yourself, I've attached the file ant-xdocs.zip which contains
a small but representative sample of task documentation in its current
state.
-Bill
Erik Hatcher wrote:
>
> I've enhanced the proposal/xdocs a bit to detect Ant tasks a lot better. It
> climbs the hierarchy looking for a parent class with an execute() method
> (except if it hits org.apache.tools.ant.Task it quits and doesn't count that
> as a task).
>
> I'm using the generation of defaults.properties as the "litmus test" to how
> good the generation is working, and it just about matches our currently hand
> maintained defaults.properties. Here are the exceptions:
>
> XDoclet generates these extras:
> ccmcheck=org.apache.tools.ant.taskdefs.optional.ccm.CCMCheck (any reason
> not to make this abstract?)
>
> iplanetejbc=org.apache.tools.ant.taskdefs.optional.ejb.IPlanetEjbc (this
> couldn't really be used by a task because of the exceptions its execute
> method throws, right? Or does that matter?)
>
> mail=org.apache.tools.ant.taskdefs.SendEmail (it also generates the
> correct mapping to EmailTask, perhaps need an 'ignore' flag?)
>
> p4delete=org.apache.tools.ant.taskdefs.optional.perforce.P4Delete
> p4reopen=org.apache.tools.ant.taskdefs.optional.perforce.P4Reopen
> p4revert=org.apache.tools.ant.taskdefs.optional.perforce.P4Revert (these
> are really tasks, but we have no mappings to them - why not?)
>
> vajload=org.apache.tools.ant.taskdefs.optional.ide.VAJLoad
>
> vajloadprojects=org.apache.tools.ant.taskdefs.optional.ide.VAJLoadProjects
> (both are the same, essentially. Can we deprecate VAJLoadProjects?)
>
> xalan1executor=org.apache.tools.ant.taskdefs.optional.junit.Xalan1Executor
>
> xalan2executor=org.apache.tools.ant.taskdefs.optional.junit.Xalan2Executor
> (Currently these look and smell like tasks, but their execute method throws
> Exception - does that take them out of the running to really be tasks?)
>
> XDoclet omits these:
> copydir=org.apache.tools.ant.taskdefs.Copydir
> copyfile=org.apache.tools.ant.taskdefs.Copyfile
> deltree=org.apache.tools.ant.taskdefs.Deltree
> javadoc2=org.apache.tools.ant.taskdefs.Javadoc
> mimemail=org.apache.tools.ant.taskdefs.optional.net.MimeMail
> rename=org.apache.tools.ant.taskdefs.Rename
> renameext=org.apache.tools.ant.taskdefs.optional.RenameExtensions (all
> of these are @deprecated)
>
> unjar=org.apache.tools.ant.taskdefs.Expand
> unwar=org.apache.tools.ant.taskdefs.Expand (several mappings to the same
> class - need to handle this situation with XDoclet - shouldn't be a problem)
>
> vajload=org.apache.tools.ant.taskdefs.optional.ide.VAJLoadProjects (need
> to resolve issue from above)
>
> I can easily bring the deprecated classes back to life, I just thought for
> grins that I'd let it ignore them for now. I don't want to start a big
> "deprecation" discussion again, and certainly removing deprecated classes
> from the mappings file breaks backwards compatibility, so we'll have to
> re-enable for the real thing.
>
> Overall, it looks like its right on track with only a few minor issues.
> Here are a few issues/ideas:
>
> - Can a class with a method 'void execute() throws Exception' be a task?
>
> - It seems that we have a few exceptions that will require an 'ant.task
> ignore="true"' kinda thing so that it gets skipped over for processing even
> though it could really be used as a task. Thoughts?
>
> - There are several tasks that point to Expand, and right now there are
> additional 'name="..."' in the class, but the template is not coded such
> that it picks that up when building defaults.properties. This should be an
> easy thing to add. But how would multiple names play out in the XML created
> for a task? Should it create multiple XML files? Or just note the multiple
> names as aliases in one XML file somehow?
>
> - Categorization - should we restrict a task to a single category? Or allow
> it to be in multiple? Or do we need a few different "bucket" types to drop
> tasks into? I've been thinking we should have a "vendor" bucket so that we
> could create groupings in documentation for all Weblogic tasks (wljspc,
> wlrun, wlstop) for example. There are lots of ways we could go with this!
> So start the brainstorming, and let me know.
>
> Erik
Re: XDoclet status update
Posted by Erik Hatcher <ja...@ehatchersolutions.com>.
From: "Jose Alberto Fernandez" <j_...@yahoo.com>
>> I'm using the generation of defaults.properties as the "litmus test" to
how
>> good the generation is working, and it just about matches our currently
hand
>> maintained defaults.properties.
>
>This is fine, but notice that defaults.properties lumps together all
classes, no matter
>if they are part of CORE (ant.jar) or of optonal.jar. When and if we moved
to
>an <antlib> model, we will need to be able to segregate things. I just
spend an
>entire day tracking a failure on the testcases when using <antlib> proposal
>and the reason was that org.apache.tools.ant.taskdefs.Get goes into
optional.jar
>instead of ant.jar (mind you its inner-classes are still in ant.jar).
Because the declaration
>was in a diferent place than the code, it was not loaded by any of them.
> So the docklet has to be able to put things in the right place.
Well, I'm all about XP, so *when* (not if :) we get to the antlib deal we'll
implement the segregation. Perhaps we should go ahead and start tagging the
classes with a library identifier also? @ant.task library="..."? We
already segregate by category for documentation purposes, so having multiple
defaults.properties generated (or whatever type of file that should morph
into in the antlib model) won't be a problem.
>> - There are several tasks that point to Expand, and right now there are
>> additional 'name="..."' in the class, but the template is not coded such
>> that it picks that up when building defaults.properties. This should be
an
>> easy thing to add. But how would multiple names play out in the XML
created
>> for a task? Should it create multiple XML files? Or just note the
multiple
>> names as aliases in one XML file somehow?
>>
>
>You mean the documentation? I think each should have its own documentation,
>the fact that the task in implemented by the same code is just an
implementation
>detail and users should not rely on that fact. We may decide to change the
implementation
>of one and not the rest.
Right now several tasks 'names' point to Expand, and the XDoclet stuff is
not handling that at the moment. So it is only generating one entry into
defaults.properties for it, and one XML file. It won't be difficult, I don't
think, to have it corrected so that Expand would create multiple entries in
defaults.properties (unjar, unwar, unzip, etc) and that a unique XML file
for each is generated also. We'll just have this:
@ant.task name="unjar" name="unwar" name="unzip"
(or some such construct) in Expand.java.
>Ok, here I am not clear what you mean by cathegories. Certaintly it would
>be nice if you could provide means to use these for roles (as on ANT2 or
<antlib>
>proposals) among other things.
Currently the "category" (@ant.task category="...") defines the grouping it
gets in the directory structure for the XML and documentation generated.
This is a high-level grouping of, for example, jar/zip/war/ear/tar into a
"packaging" category.
Peter and Adam are already discussing stealing this stuff for myrmidon - so
I'm sure they'll be merging it together with the previous prototype role
metadata generation that I did for them originally there.
If we need some kind of mapping to antlib roles that won't be difficult to
add either. At this point I'm tossing it out there as-is and will do the
best I can to improve it, but thanks to Bill's nice work I encourage you to
give it a shot (just run 'ant docs' in proposal/xdocs directory) and see the
output (build/gen & build/docs) for yourself and then suggest improvements.
Its amazing how close we are with this thing, especially with the ability to
merge in external files with the merge points giving us the ability to pull
in the description and examples from the existing documentation. I am
considering writing a little JTidy-based tool that will convert the HTML
docs into the XML format Bill mocked up for a few tasks. I'm not sure if
this is worthy of my time just yet, so I think I'll hold off and find out
what else shakes out from all this.
Erik
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XDoclet status update
Posted by Jose Alberto Fernandez <j_...@yahoo.com>.
From: "Erik Hatcher" <ja...@ehatchersolutions.com>
> I've enhanced the proposal/xdocs a bit to detect Ant tasks a lot better. It
> climbs the hierarchy looking for a parent class with an execute() method
> (except if it hits org.apache.tools.ant.Task it quits and doesn't count that
> as a task).
>
Great!
> I'm using the generation of defaults.properties as the "litmus test" to how
> good the generation is working, and it just about matches our currently hand
> maintained defaults.properties.
This is fine, but notice that defaults.properties lumps together all classes, no matter
if they are part of CORE (ant.jar) or of optonal.jar. When and if we moved to
an <antlib> model, we will need to be able to segregate things. I just spend an
entire day tracking a failure on the testcases when using <antlib> proposal
and the reason was that org.apache.tools.ant.taskdefs.Get goes into optional.jar
instead of ant.jar (mind you its inner-classes are still in ant.jar). Because the declaration
was in a diferent place than the code, it was not loaded by any of them.
So the docklet has to be able to put things in the right place.
> Overall, it looks like its right on track with only a few minor issues.
> Here are a few issues/ideas:
>
> - Can a class with a method 'void execute() throws Exception' be a task?
>
> - It seems that we have a few exceptions that will require an 'ant.task
> ignore="true"' kinda thing so that it gets skipped over for processing even
> though it could really be used as a task. Thoughts?
>
I think we need this for maintainability. We may want to control which
classes are exposed as tasks in a particular release. We may want to
provide a new implementation for the XML task, but still need to leave
the old class in there in case someone extended it. But we just do not
expose it as available.
> - There are several tasks that point to Expand, and right now there are
> additional 'name="..."' in the class, but the template is not coded such
> that it picks that up when building defaults.properties. This should be an
> easy thing to add. But how would multiple names play out in the XML created
> for a task? Should it create multiple XML files? Or just note the multiple
> names as aliases in one XML file somehow?
>
You mean the documentation? I think each should have its own documentation,
the fact that the task in implemented by the same code is just an implementation
detail and users should not rely on that fact. We may decide to change the implementation
of one and not the rest.
> - Categorization - should we restrict a task to a single category? Or allow
> it to be in multiple? Or do we need a few different "bucket" types to drop
> tasks into? I've been thinking we should have a "vendor" bucket so that we
> could create groupings in documentation for all Weblogic tasks (wljspc,
> wlrun, wlstop) for example. There are lots of ways we could go with this!
> So start the brainstorming, and let me know.
Ok, here I am not clear what you mean by cathegories. Certaintly it would
be nice if you could provide means to use these for roles (as on ANT2 or <antlib>
proposals) among other things.
Jose Alberto
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: XDoclet status update
Posted by Peter Donald <pe...@apache.org>.
On Sun, 3 Mar 2002 13:27, Erik Hatcher wrote:
> I've enhanced the proposal/xdocs a bit to detect Ant tasks a lot better. It
> climbs the hierarchy looking for a parent class with an execute() method
> (except if it hits org.apache.tools.ant.Task it quits and doesn't count
> that as a task).
Yea!
> mail=org.apache.tools.ant.taskdefs.SendEmail (it also generates the
> correct mapping to EmailTask, perhaps need an 'ignore' flag?)
+1 to ignore or more likely a "replace" tag.
+1 to allowing you to also add aditional mappings
> - Can a class with a method 'void execute() throws Exception' be a task?
Yep - it can be wrapped in an adaptor that will convert a raw exception to a
build exception.
> - It seems that we have a few exceptions that will require an 'ant.task
> ignore="true"' kinda thing so that it gets skipped over for processing even
> though it could really be used as a task. Thoughts?
+1
> - There are several tasks that point to Expand, and right now there are
> additional 'name="..."' in the class, but the template is not coded such
> that it picks that up when building defaults.properties. This should be an
> easy thing to add. But how would multiple names play out in the XML
> created for a task? Should it create multiple XML files? Or just note the
> multiple names as aliases in one XML file somehow?
+1 for aliases in one file
> - Categorization - should we restrict a task to a single category? Or
> allow it to be in multiple? Or do we need a few different "bucket" types
> to drop tasks into? I've been thinking we should have a "vendor" bucket so
> that we could create groupings in documentation for all Weblogic tasks
> (wljspc, wlrun, wlstop) for example. There are lots of ways we could go
> with this! So start the brainstorming, and let me know.
hmmm ... not sure. I could definetly see it being useful for multiple
categorys and even category hierarchies ...
Maybe something like the following would place the wljspc task into multiple
categories.
@ant.category web weblogic jsp
We could even have "." as a hierarchy separators so that we could have
hierarchial groups ala
@ant.category ant.io
@ant.category ant.runtime
@ant.category weblogic.jsp
Question - are these groupings likely to reflect ant2 groupings of takss into
librarys? Looks like it.
--
Cheers,
Pete
*---------------------------------------------------------*
| Contrary to popular belief, UNIX is user-friendly. It |
| just happens to be selective on who it makes friendship |
| with. |
| - Richard Cook |
*---------------------------------------------------------*
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>