ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bruce Atherton <>
Subject Re: Speaking of deprecation...
Date Thu, 07 Feb 2002 23:52:58 GMT
At 11:44 AM 2/5/2002 -0800, Diane Holt wrote:
>To clean up old cruft. I just don't see any need to keep including in the
>documentation stuff that we don't want people using anyway.

Is there any harm in documenting it as deprecated, and then removing it 
altogether once the feature is actually removed according to the 

The reason I think this is a better idea is that users will Know up front 
that a feature is deprecated. Right now, I can't tell whether something 
doesn't exist in the documentation because no one has gotten around to it 
or because it has been removed. I often rely on <antstructure> to tell me 
what I can REALLY do in terms of attributes. And forcing someone to build a 
system that uses a feature in order to find out that feature is deprecated 
strikes me as badness.

Then there is the question of learning how ant works by reading other 
people's build files. If the build files work and you can't figure out how 
they work by reading the documentation, that can be a frustrating 
experience for a new user (who may not recognize the significance of the 
deprecation warnings when they come up).

So why not have the documentation match the program as much as possible? 
Document deprecation, and remove documentation for removed features.

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

View raw message