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
