On 5/27/10 11:30 AM, Peter Lind wrote:
Sure, but @param, @access and possibly @return are but a part. I stand
by my words: document the parent as a stub and provide actual
documentation for the real implementations. Otherwise you're trying to
be *clever* and will see the age-old result: you'll end up shooting
yourself in the foot or worse places.
Regards
Peter
... What's "clever" about using OO inheritance the way it's designed to be
used? Are you actually suggesting that the solution is to insist on
duplicating the docblock in every child class, which is a huge maintenance
headache?
If the implementations are the same in all child classes, then you're
doing OO horribly wrong.
Of course the implementations aren't the same. That would be silly.
But the API is the same, by design.
If they're *not* the same, then you'll merely
be duplicating a part of the documentation (docblocks do *not* just
consist of @param and @access) while writing the rest of the
documentation to show what you're actually doing different in each
method.
I generally do not put a description of the entire internal algorithm
into the docblock, as that is not part of the API. That's also by
design. Even if there is implementation-specific stuff to add, the
"short description line", @params, @return, and lots of other things
don't change, nor should they. So at best you're duplicating half the
docblock each time. Still a high maintenance burden.
--Larry Garfield
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
