ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Erik Hatcher" <jakarta-...@ehatchersolutions.com>
Subject Re: Docs out of sync
Date Thu, 20 Jun 2002 11:48:34 GMT
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" <jakarta-ant@ehatchersolutions.com>
To: "Ant Developers List" <ant-dev@jakarta.apache.org>
Sent: Thursday, June 20, 2002 5:39 AM
Subject: Docs out of sync


> ----- Original Message -----
> From: <stevel@apache.org>
> >   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:ant-dev-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>
>
>


--
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