Re: @deprecated

[Mark Wielaard]

Hi Stuart,

On Fri, 2005-09-02 at 11:56 -0400, Stuart Ballard wrote:
> On 9/2/05, Mark Wielaard <address@hidden> 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