Hi Stuart, On Thu, 2005-09-01 at 23:54 -0400, Stuart Ballard wrote: > hence getting an almost instant 0.3% improvement in japi scores which > incidentally would push us over 90% of 1.4, which is a nice little > psychological milestone :) > > The downside of such a script would be that, at least if done naively, > none of the @deprecated tags would get any comments indicating *why* > the item is deprecated or what should be used instead. > > So I'm interested in feedback on whether it's worthwhile to write a > script to add these @deprecated tags or not; basically, is an empty > deprecated tag better or worse than no deprecated tag at all on > something that is deprecated in the JDK?
I am all for breaking psychological milestones (although wasn't there a saying that the last 10% of the work will be the other 90% of effort needed?) But I am not a big fan of producing generated comments by scripts that are supposed to explain what our code actually does. And often these kind of automagically generated doc strings never get properly updated. The problem is that you want to really describe why something is deprecated, what the replacement and/or reason for it is and/or how the behavior might have changed from earlier versions. There is also the problem that in a couple of places we do actually implement the deprecated behavior or don't yet have the replacement behavior. In such cases marking our implementation deprecated is not helping our users. I would prefer an approach were someone goes over the list by hand, reading our implementation to see what we actually do and write real @deprecated explanations and possibly write the changed/replacement methods when needed. That is a bit more work, but produces real valuable documentation for our users. Cheers, Mark
signature.asc
Description: This is a digitally signed message part
_______________________________________________ Classpath mailing list [email protected] http://lists.gnu.org/mailman/listinfo/classpath
