Re: Method documentation

On Thu, May 27, 2010 at 3:59 PM, Waynn Lue <waynnlue@gmail.com> wrote: > I've seen @inheritDoc used in Java before, though I'm not sure about > the php support. > > Waynn > > On 5/27/10, Adam Richardson <simpleshot@gmail.com> wrote: > >> > >> > >> > Larry, > >> > > >> > I've thought about this very issue before (java developers sometimes > >> lament > >> > this issue, too), and I error on the side of duplication if I'm using > >> > inheritance. > >> > > >> > However, I'd say I rarely use inheritance for anything in my > >> > development, > >> > and I'm much more likely to use composition. > >> > > >> > When a project evolves that's built almost entirely using design > >> > patterns > >> > focused on composition, I find that I very rarely have to duplicate > any > >> > documentation, or rework documentation later on because a completely > new > >> > component is being used. > >> > > >> > Outside of PHP (Scala, Objective C, F#, etc.), it seems like > inheritance > >> is > >> > advocated much less frequently, due to the power and simplicity of > >> > composition (e.g., change behavior at runtime, requires less knowledge > >> > of > >> > the parent classes.) > >> > > >> > Quoting the Head First book on design patterns: > >> > "Favor composition over inheritance" > >> > > >> > Now, there are situations where either inheritance is the most > >> appropriate, > >> > and/or the architecture is not directly under your control. And, as I > >> said > >> > at the beginning, I tend to error on the side of duplication. I just > >> > try > >> to > >> > never put myself in that situation :) > >> > > >> > Adam > >> > > >> > -- > >> > Nephtali: PHP web framework that functions beautifully > >> > http://nephtaliproject.com > >> > > >> > >> With the up-and-coming traits facility for PHP, it will be interesting > >> on how this gets resolved for documentation readers. > >> > >> > > Indeed, I'm excited for the new capabilities, but they won't come easily > in > > terms of the development ecosystem. > > > > -- > > Nephtali: PHP web framework that functions beautifully > > http://nephtaliproject.com > > > > -- > Sent from my mobile device > You're absolutely right, Waynn, Phpdocumentor has this, too: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineinheritdoc.pkg.html However, Netbeans (and I'm assuming other PHP IDE's, but I'm only using Netbeans) doesn't parse the inheritdoc element so its info is available with code-completion. I think Larry was trying to find something that would work for both generated documentation AND IDE auto-complete capabilities. Adam -- Nephtali: PHP web framework that functions beautifully http://nephtaliproject.com