Re: Method documentation

On 27 May 2010 17:57, larry@garfieldtech.com <larry@garfieldtech.com> wrote: > On 5/27/10 10:43 AM, Peter Lind wrote: > >> You're overriding the function. IDEs should *not* show the parent >> documentation, because the parent function does *not* get called. It >> only gets called if you do a specific parent::hello($a, $b); > > *snip* > >>> So it seems like no matter what I do, someone gets totally screwed with >>> useless documentation (either IDE users, plain text editor users, >>> code/documentation maintainers, or people looking at the documentation >>> online in Doxygen or PHPDoc).  Is there an alternative I'm missing that >>> doesn't suck?  What do most people do to deal with this trainwreck? >>> >> >> Personally, I think this issue stems from a wrong way of thinking >> about methods and overriding them. You're either not documenting the >> overriding methods properly or overriding methods for no real reason. >> At least, that's how it looks from here (and my apologies if I got it >> completely wrong :) ). >> >> Regards >> Peter > > 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 -- <hype> WWW: http://plphp.dk / http://plind.dk LinkedIn: http://www.linkedin.com/in/plind BeWelcome/Couchsurfing: Fake51 Twitter: http://twitter.com/kafe15 </hype>