ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Erik Hatcher" <jakarta-...@ehatchersolutions.com>
Subject Re: [xdocs] Feature Requests
Date Wed, 06 Mar 2002 12:53:16 GMT
----- Original Message -----
From: "Peter Donald" <peter@apache.org>

> I was just playing around with the xdocs proposal and I have a few
requests ;)
>
> * Could you rename your templates to end with .j as that *seems* to be the
> standard that most other xdoclet templates use (though I could be wrong).

Ummm, no!  :)  I don't like the .j extension.  I have a feeling it was a
holdover from when XDoclet was EJBDoclet and it was designed to be .java
template. We aren't creating .java files - but a lot of XDoclet's builtin
stuff is.

I prefer .template.

> * If someone was to create "summary" pages for each category of
> tasks/datatypes that listed all the types in that category and maybe gave
a
> blurb about category (blurb got via merge external xml operation?) then
that
> would be fantastic.

Bill??

> * Rather than defaulting to "other" as catgory if it is undefined -
perhaps
> it would be a good idea to default to the last element in package name in
> which the task is contained. So tasks in
>
> o.a.t.a.taskdefs.optional.vss
>
> would be in the "vss" category if none other was specified. This would
make
> it much easier to also use code unchanged for ant2 ;)

Thats a good idea!  Perhaps we could have that as a configurable option what
the default category is.  I'm not going to concern myself much with the
category stuff at the moment beside perhaps making this change because I
feel the most important thing is for us to get the generated documentation
as good as the current HTML documentation.  Once there, we can then migrate
that proposal to the main code base.  Then we can have a field day with
categories and other such features!

> * Also it does not seem that nested elements are processed proeprly - or
am I
> missing something. ie Are top level elements and nested elements treated
> identically? ie will the structure of a nested element be fully documented
?

We're going to work on this.  I haven't had a look at Ara's pointer to the
recursive templates, but will do so soon and likely integrate that (unless
Bill beats me to it) into our templates to have it recursively output nested
elements.  We'll add some "stop" logic for it to cease the recursion when a
known datatype is found.

> * Also it would be great to write the task so that only the changed files
are
> passed to the xdoclet engine. Because each file generates a separate xml
then
> this should not be a problem.

I think we'd have problems when doing the element recusion then though -
we'd need all the classes in the XDoclet "model" when generating task
documentation.

> To generate the defaults.properties files you
> can post-process all the generated xml files to extract filenames as
> appropriate. This would allows us to have xdoclet fully integrated into
our
> buikld process with virtually no speed hit

True - we'd need to capture the "ignore" flag into the XML files then
though, which we aren't currently.

I am also going to add the output of general (currently unrecognized)
"@ant." tags to the XML so that its extensible and grabs stuff without even
needing to know about it explicitly.  This will allow us to drop special
tags in, have them appear in the XML, and then do what we want with them
later without having to modify the template.

    Erik



--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message