Hi Stuart, On Fri, 2005-09-02 at 11:56 -0400, Stuart Ballard wrote: > On 9/2/05, Mark Wielaard <[EMAIL PROTECTED]> wrote: > > 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. > > Ok. No promises, but if I do write a script then it'll be an > interactive one which uses human intervention to get a correct and > complete deprecation comment. Would you agree that it's fine to refer > to Sun's documentation to write these, as long as the actual text > chosen is written from scratch to convey the same information?
If you mean the javadoc that Sun puts up that is certainly one of the things you can use for such things. But in general I find Sun's javadoc not that good. (We try to do better, but I am sure we also fail at times.) You certainly cannot write good (better!) documentation for GNU Classpath from just that. You really need to have an overall feeling of how the class/package is designed to write good documentation. That is why it is important that people writing the code for a package also document it. Then you must have studied all the material available and have the big picture knowledge that is needed. > > 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. > > Hmm, I'm not sure I agree with this. Seems to me that even if we > haven't yet implemented a replacement, it's useful for users to know > if they're using a deprecated API, because then they'll be aware that > eventually they're likely to want to switch, once the replacement does > get implemented. A good deprecation comment might also make the users > aware of fundamental problems with the API itself, such as in the case > of Thread.stop(), which might lead them to take an entirely different > approach even if a direct replacement isn't (yet or ever) available. Sure, but that does depends on good @deprecate annotation comments. And although we are making good progress, it would be foolish to promise anything in the future unless we are certain someone is actually working on it. Guess it just comes down to me liking scripting for any post processing or signaling of issues, but not for generating code/comments automatically. I have just seen it "rot" too often. In such cases it is better if there is no comment at all instead of automagically generated comments that potentially never get fixed. But please don't take my comments as saying not having good deprecation information is acceptable. It isn't. I am just worried about the information being good and properly documented. Please do work on this. And luckily it seems most of the work can be done by choosing a different way of compiling/constructing the glibj.zip you use for the japi overview. Cheers, Mark
signature.asc
Description: This is a digitally signed message part
_______________________________________________ Classpath mailing list [email protected] http://lists.gnu.org/mailman/listinfo/classpath
