Re: Documenting grandparent inheritance

On Tue, Jun 10, 2014 at 7:02 PM, Adam Harvey <aharvey@php.net> wrote: > My fellow documentors, > > We have https://bugs.php.net/bug.php?id=67379 open at the > moment, > which correctly points out that we only document the methods inherited > from GlobIterator's immediate parent, rather than all the methods it > inherits from its ancestors (which is a considerably longer list). We > can fix this by adding the relevant <xi:include> elements below the > existing parent one, but it got me to thinking whether we can do this > more automatically. > > My first thought was to do this in PhD, but we'd effectively have to > reimplement xi:include's semantics in the rendering logic there, which > seems suboptimal to say the least. > > The one place where it seems we could do this is in > doc-base/configure.php: once we have the manual in DOM, we can look > for an arbitrary element in the phpdoc namespace and then use XPath > voodoo to replace that element with the correct xi:include elements. > I've created a gist with the relevant patches for doc-base and a > couple of sample en files: > https://gist.github.com/LawnGnome/ade9fffb66b77d369e49 > > The thing is: I'm not really convinced this is a good idea, so I want > input. Is this worth pursuing, or are we better off manually > maintaining multiple <xi:include> elements for classes that have a > deeper inheritance hierarchy than just a single parent? > Does it add a minute processing time to configure.php? Doing the xincludes manually allowes you to tweak the order, just like with its own methods - you can ensure the ctor is at the top, dtor at the bottom, and the others alphabetically after the ctor, inherited after that, ... ... .... If we can do this automagically we have one less thing to manually remember to do so that sounds good! :) -Hannes