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
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
