Re: Documenting grandparent inheritance

On 11 June 2014 03:02, 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? > > Adam I'm +1 on the general idea. In fact I wonder whether it could be taken a step further, and do it automatically for all classes instead of requiring a magic element to be present? Since that element would have no meaning without configure.php, it doesn't seem like it's necessary for it to be present at all.