Re: Documenting grandparent inheritance

On Thu, Jun 12, 2014 at 2:51 AM, Chris Wright <daverandom@php.net> wrote: > 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. It needs to be there cause PhD doesn't have the data to generate the hierarchy without it. -Hannes