On a related note, I view the auto-generation of docs somewhat like the
effect extensive JUnit testing has on a project in that you inevitably end
up writing more API-friendly code when using JUnit because it helps in
writing test cases to get good coverage.
Auto-generating the docs will push us to keep our task interfaces cleaner
and less complex, at least in theory, that is! :)
Erik
----- Original Message -----
From: "Erik Hatcher" <[EMAIL PROTECTED]>
To: "Ant Developers List" <[EMAIL PROTECTED]>
Sent: Thursday, June 20, 2002 5:39 AM
Subject: Docs out of sync
> ----- Original Message -----
> From: <[EMAIL PROTECTED]>
> > I've realised that we now have a synchronisation problem; as soon as
1.5
> goes out the door, we should really migrate to xdoc based docs ASAP.
>
> Yes, the more I've compared side-by-side the setters to our actual docs
the
> more I cringe. We've got lots of issues in this realm where some
attributes
> exist in code but are not documented (this is on purpose in some cases).
We
> have cases where we are subclassing a task and then turn around and
> unsupport lots of its setters by throwing a BuildException in the setter -
> when what really should be done is refactor the common stuff out and allow
> subclasses to really be subclasses and not some weird partial support of
the
> parent functionality.
>
> After 1.5 we can really start comparing what xdocs generates and try out
the
> migration to it.
>
> The main dilemma is how to auto-generate or merge in the rich type of
> information we have in our HTML files where some attributes are allowed if
> others are specified and the complex interactions between attributes that
> exists in the code and is easily described in free-form text but not so
easy
> to auto-generate.
>
> Erik
>
>
>
> --
> To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
>
>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
