ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bill Burton" <>
Subject Re: [xdocs] Feature Requests
Date Thu, 07 Mar 2002 00:40:18 GMT

Erik Hatcher wrote:
> ----- Original Message -----
> From: "Bill Burton" <>
> > A while ago when I went hunting for the XDoclet stuff in myrmidon, I had
> > no idea that the files with .template were related to XDoclet.  On the
> > other hand if they were .j,  I wouldn't have known either because I didn't
> > know anything about XDoclet :) . Although .j may not be a very good
> > convention, it is a convention nonetheless.
> It is indeed a convention, but one I feel worthy of breaking because .j ->
> .java
> Maybe we should make them be .x files!  :)

Or, maybe .xdt (XDoclet Template).  This is the same prefix used for all
tags (XDt:...).

> > What I'd really like is a way of specfying how tasks are classified into
> > categories at the Ant task level much the way the <group> element works
> > for javadoc or in an XML file.
> You mean -group?  What is <group>?  I didn't know about -group but just
> looked it up, 

Yes, -group for command line javadoc.  

> and it certainly seems reasonable to be able to recategorize
> things after the XML has been generated.

The more I think about it, the more reasonable it seems :) .

> > I think getting the dependency checking working well under most cases is
> > rather important.  If committers have to regenerate all the XML because of
> > a little change to one task, it won't go over well.  Initially, the task
> > could handle dependency checking like the <style> or <dvsl> tasks where
> > newer source causes the respective target XML to be regenerated.  But if
> > the XDoclet template is newer, then everything is regenerated.  Handling
> > other dependencies such as changes to datatypes or source XML's could be
> > done with <uptodate>.
> I think you and Peter are missing something (or I am!).  If we only feed
> into XDoclet because only that file changed, then how would
> we enumerate the elements for FormatterElement (addFormat)?  You can't
> (again, unless I'm missing something major here).
> I don't currently know a solution for this except to wait the minute and a
> half that it takes to generate all of those files for the current Ant
> codebase.  Its not like you'd need to run that process for every build, only
> if you wanted to regenerate docs or
> Or we could just keep bugging Ara to get xjavadoc finished!  :)  (which
> promises multiple times improvement in speed)

Or, process just datatypes first separately.  From that, generate a
patternfile listing all datatypes classes.  With proper dependency
checking, this wouldn't need to be run very often.  If datatypes XML did
need to be generated, this would trigger a full build of the tasks XML.

Then, assuming no datatypes have changed, process the desired tasks based
or dependency information while also including all datatype classes via
the previously generated patternfile. 

Would that do it?

> > Yes, I'd considered that as well.  The problem is both the <dvsl> and
> > <style> tasks don't have a way to use a fileset is input with only a
> > single file as output.  I was considering fixing this in the <dvsl> task
> > or even implementing support for a merge mapper.  However, XDoclet already
> > has all info for the classes loaded in memory so it's really quick to run
> > another template to generate a single file like
> Yes - agreed.  Adding more and more templates won't affect our processing
> speed much - its the initial javadoc load of the source code that is slow -
> and with the above mentioned issue I'm not sure there is a way around doing
> that full load.

Another issue is that the static XML documentation associated with each
task/datatype can be edited which currently requires regenerating via
XDoclet because the XDoclet template includes the static XML.  So there's
yet another dependency.  I'd assumed these static XML files should be
located alongside the respective .java files.  However, for dependency
purposes, they may have to be located in xdocs/manual/* in the same
relative location as the generated XML and HTML.  Then <dependset> can be
used to delete the XDoclet generate XML causing XDoclet to rebuild the XML
for those tasks and datatypes.

For some of these reasons, I've been thinking it would be better to
include the XDoclet generated XML within the static XML rather than the
other way around as it's happening now.  This means the XML static file
can be updated to fix many documentation issues without running XDoclet
because the merge is ocurring when the HTML is generated rather than when
the XML is generated.  It makes for one less dependency on XDoclet where
it really isn't necessary anyway.

>     Erik


To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message