On 27 May 2010 17:15, larry@xxxxxxxxxxxxxxxx <larry@xxxxxxxxxxxxxxxx> wrote:
> Hi folks.
>
> OK, so here's the deal. I am trying to figure out the "right" way to
> document methods in OO code that includes method overriding in child
> classes. Simple, right? Unfortunately, it seems the tools out there are
> making this much more complicated than it should be. Example:
>
> class Foo {
>
> /**
> * Says hello.
> *
> * Lengthier description of this method.
> *
> * @param int $a
> * The first variable.
> * @param int $b
> * The second variable.
> * @return string
> * A message.
> *
> */
> public function hello($a, $b) { /* ... */ }
> }
>
> class Bar extends Foo {
> public function hello($a, $b) { /* ... */ }
> }
>
> Seems simple, right? Here's the problem(s):
>
> - If I put no docblock on Bar::hello(), every IDE I've tried shows no
> documentation whatsoever when I do $b = new Bar; $b->he... It will
> auto-complete, but does not provide any documentation. Documentation
> parsers (PHPDoc, Doxygen, etc.) will detect that and show the parent
> method's docblock, however, and it's easy to maintain.
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);
> - If I put no docblock on Bar::hello(), someone just reading the code
> visually has no idea what the method does, or what parent class or interface
> it comes from that might contain documentation.
Again, the function doesn't come from a parent. The user should read
the function they're looking at to find out what it does. Checking the
overridden function only makes sense if it's explicitly called.
> - If I put a subset of the documentation on Bar::hello, an IDE shows only
> that subset, which is frequently inadequate. Documentation parsers also, as
> far as I know, will then only show the abridged version.
>
> - If I duplicate the documentation on Bar::hello(), it shows up in an IDE
> and is there for people reading it, but it still doesn't say what interface
> or parent class it comes from.
I honestly don't see why one would ever want this information. You're
defining the function in the current class - whether or not it's
defined in the parent class has no effect on what function you'll get
when you call an object of *this* class.
> - If I duplicate the documentation on Bar::hello(), that's a ton of
> duplicate content that I will then have to always keep in sync as the system
> evolves. (Rather, that everyone will have to as this is a large
> multi-person project.)
Then document the parent method as being a stub that should be
overridden. Document the overriding method - which presumably has
actual code in it - properly.
> - If I make a docblock that is just a "Overrides Foo::hello()", then it's
> easy to maintain and there's no duplication, but the IDE assistance is
> useless and the documentation parsers I know of will all show that as the
> only description, which is not all that useful.
IDE assistance would always be useless: if you're overriding the
parent method it *has* to be because the behaviour is different than
from the method in the parent class. Hence, the method should have
it's own documentation - otherwise, why bother with documentation at
all?
>
> 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
--
<hype>
WWW: http://plphp.dk / http://plind.dk
LinkedIn: http://www.linkedin.com/in/plind
BeWelcome/Couchsurfing: Fake51
Twitter: http://twitter.com/kafe15
</hype>
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
