On 27 May 2010 17:21, larry@xxxxxxxxxxxxxxxx <larry@xxxxxxxxxxxxxxxx> 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? > > 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 > > -- > PHP General Mailing List (http://www.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > > Just because the params and return type are the same, you would have to document the methods purpose. So may as well include the params and return. There is the http://manual.phpdoc.org/HTMLframesConverter/phphtmllib/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html which will allow you pull in the description... Ideally there needs to be something like an inheritparams, inheritreturn and maybe inheritall. You also have http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblocktemplate, but I can't see how that is useful beyond a single class. By that I mean, I don't think you can clone the content of one docblock in the interface into the docblock of the class. But overall, I agree with Peter. Richard -- ----- Richard Quadling "Standing on the shoulders of some very clever giants!" EE : http://www.experts-exchange.com/M_248814.html EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 ZOPA : http://uk.zopa.com/member/RQuadling -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
