Re: Method documentation

On 27 May 2010 18:21, larry@garfieldtech.com <larry@garfieldtech.com> wrote: > 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? If the implementations are the same in all child classes, then you're doing OO horribly wrong. If they're *not* the same, then you'll merely be duplicating a part of the documentation (docblocks do *not* just consist of @param and @access) while writing the rest of the documentation to show what you're actually doing different in each method. > 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.. I honestly doubt you're doing things optimally, if you're having problems this big. I've never come across this problem, but maybe that's just me. Anyway, I don't have other advice to offer, so I'll refrain from posting again, as I'm obviously not helping you. Regards Peter -- <hype> WWW: http://plphp.dk / http://plind.dk LinkedIn: http://www.linkedin.com/in/plind BeWelcome/Couchsurfing: Fake51 Twitter: http://twitter.com/kafe15 </hype>