Re: Method documentation

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