|
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 http://www.doc.com | if I didn't, I'd eat it, and you | know how I hate the stuff.
[Prev in Thread] | Current Thread | [Next in Thread] |