On Thu, 7 Feb 2002, Magesh Umasankar wrote: > > I agree with Bruce. Documentation should reflect > > the code. If a feature is in the code, it should > > be in the documentation. If a feature is deprecated > > in the code, it should be marked as deprecated in > > the documentation but it should still be described. > > OK, though I would like to somehow strongly discourage > use of deprecated features...
As usual, I have a different opinion on the issue - I would like to somehow strongly discourage the use of deprecation ! Removing a feature from documentation is IMHO even worse than removing it from the code - while I can accept that some features were 'bad' and shouldn't be supported ( for very good reasons, like 'we prefer a different name for this attribute' ), they should remain in the documentation with the 'deprecated' mark and maybe a justification for the reason it was deprecated and who made the decision and when. I really _hate_ the 'deprecated' message in ant. Especially when it's because someone has a different taste and doesn't like the old name. So I'm -1 on removing deprecated freatures from docs, the same as I'm -1 on removing deprecated features without a very solid reason ( like that for Thread.stop() ). JDK1.4 is still backward compatible with JDK1.1, including a lot of stuff that's far worse than 'licence versus license' naming preferences. If you have a problem a feature, say -1 when it is added or before the release. Or before it is documented. Costin -- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
