Re: Method documentation

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. To wit: interface Talk { /** * Prints a message in the appropriate language. * * @param $message * A key indicating the message to pull from the DB * and print. * @return boolean * TRUE if it worked, FALSE otherwise. */ public function hello($message) {} } class TalkInSpanish implements Talk { public function hello($message) {} } class TalkInKlingon implments Talk { public function hello($message) {} } The documentation for both concrete implementations is identical. If $message means something different for the Klingon implementation, or if the return changes, then that's a critical bug. You're breaking the interface. But if I do: $talk = resolve_language(); $talk->hello(... Then I should get code assistance, and my doc parser should show useful information for TalkInKlingon::hello(), and someone just reading TalkInKlingon (which may be in a different file than Talk) should be able to easily figure out what $message means. As of yet, I've not figured out a way to get all three that doesn't involve tons of repeated copying and pasting and wasting time and lines. --Larry Garfield