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.

- 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.

- 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.

- 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.)

- 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.

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?

--Larry Garfield

PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

Reply via email to