[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Public methods description should be in header files

From: Adam Fedor
Subject: Re: Public methods description should be in header files
Date: Sun, 13 Oct 2002 19:29:34 -0600
User-agent: Mozilla/5.0 (X11; U; Linux ppc; en-US; rv:1.0.0) Gecko/20020610

Alexander Malmberg wrote:

Up to date ... ?  The API is not supposed to change.  Changing the
implementation of a method in such a way that it behaves differently to
the caller can have a lot of complicated and far reaching consequences for
the gnustep-base or gnustep-gui libraries, so should be quite a rare
event, and a lot of thought must be put into before doing it ... in those
cases you should of course document the changes - but these cases
are/should be the exceptions, not the rule.

Well, the current implementations of many things don't work as they're
"supposed" to work, so I don't think these changes will be that rare
(yet). IMHO, the documentation (preferably in the headers) should
document the intended behavior, and changing the implementation to match
that should be ok (even when it breaks things). This way, changing the
documentation should happen only rarely and after due consideration, and
"up-to-date" is meaningless.

I think Richard and I meant up-to-date in the sense that MOST of the documentation hasn't even been written yet, and when somebody improves or implements a method they are more likely to (and are encouraged to) document the method they are improving and/or implementing. It's easier to do this if they can document it in the same place as the code they add.

There's nothing religious about doing this though. The simple fact is that I though we had discussed this many months ago and had come to a reasonable agreement on it. Changing back seems like such a pain. Richard has done a lot of work documenting the base library - way more than anyone else - and he has been doing it this way for a long time.

Adam Fedor, Digital Optics Corp.      | I'm glad I hate spinach, because                    | if I didn't, I'd eat it, and you
                                      | know how I hate the stuff.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]