ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bill Burton" <bi...@progress.com>
Subject Re: XDoclet status update [PATCH] attributes; merge points
Date Sun, 03 Mar 2002 07:17:24 GMT
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
Mime
View raw message