Re: Documenting grandparent inheritance

On Jun 11, 2014, at 9:34 AM, Hannes Magnusson <hannes.magnusson@gmail.com> wrote: > 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! :) Agreed, as simply keeping the version.xml / versions.xml files up-to-date is difficult enough :) If this ends up being too difficult then perhaps a QA related tool can be created that locates these problems and later we can fix them manually. Regards, Philip