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 Proposal
Date Wed, 27 Feb 2002 12:45:54 GMT
----- Original Message -----
From: "Adam Murdoch" <adammurdoch_ml@yahoo.com>

> > Anyway, have at it!  I look forward to your feedback and improvements.
> >
>
> Wow.  This is very cool.

Thanks!

> Some minor comments:
>
> * It looks like the template is picking up nested classes when generating
> the default.properties file.  For example, there's a task called
> 'ant.reference' in there that points to class taskdefs.Ant.

Yes, I hadn't converted the <template> to generate defaults.properties to
use my AntSubTask. That is what is responsible for filtering out the classes
processed.  Thats just simple change to build.xml.

> * I wonder if might be worth adding an (optional) @ant:description tag,
> which would take precedence over the comment.  It might be useful at times
> to be able to add comments to a class or method, that don't end up in the
> user guide.

I'm open to discussion on how we should structure our Javadoc comments to
facilitate this. I think just having the convention that what we write in
class level Javadocs are what is seen in the documentation seems ok to me
(the short description is the first sentence, the long description is the
entire class level javadoc comment).

> * Should we add the equivalent of the user manual's "required" column
> somewhere?

Yes!  This is where we are headed with this.  It gets tricky when you have a
"one of these is required" scenario as we have with lots of our attributes,
but we'll just have to chalk that one up for the comments I think.

> * I guess we need to handle the data types as well.  Seems like it should
be
> straight-forward enough.

Yes.  I wasn't sure how we should do that.  Certainly the special datatypes
that we recognize for attributes (File, boolean, primitives/wrappers) should
be noted specially. But its much more extensible than that with a String-arg
constructor class being possible too, not to mention the
EnumeratedAttributes.

If there are no objections, I'll go ahead and commit my @tag additions to
the other top-level tasks (since its just javadoc comments, I figured it was
best to stick with the main source than to put that into the proposal too).

    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