Re: Method documentation

On 5/27/10 11:13 AM, Peter Lind wrote:

I'm overriding the method because I want to change the *implementation*. The *interface* of it, which is documented in the docblock, should not change and it's a bug (and possibly compile error) if it does change. You cannot, for instance, change what parameters the method takes in a subclass. If you change the meaning of those parameters then you're setting yourself up for crazy and hard to debug bugs. So the @param documentation absolutely should be the same for both.

Sure, but @param, @access and possibly @return are but a part. I stand by my words: document the parent as a stub and provide actual documentation for the real implementations. Otherwise you're trying to be *clever* and will see the age-old result: you'll end up shooting yourself in the foot or worse places. Regards Peter

... What's "clever" about using OO inheritance the way it's designed to be used? Are you actually suggesting that the solution is to insist on duplicating the docblock in every child class, which is a huge maintenance headache? I could go through a dozen other examples where this problem exists where there's nothing "clever" (when that became an epithet I don't know) going on, just rudimentary OO, but I won't clog the list with it. What I'm doing in the previous examples is in no way esoteric. This is OO 101 code. --Larry Garfield