Integration with API Doc Generation Tool

One thing that's cool about the PHP manual is the user comments, which do alot to explain the quirks and details of PHP's function libraries. The basic idea is good but it requires manual administration by the phpdoc team.

Would be great to be able to integrate DokuWiki with a tool like phpDocumentor ¹⁾ or phpXref for the same purpose - add user input to generated document.

The basic approach these tools take is to scan a collection of source files, build up the documentation in memory then spit out the results as HTML.

Would would be cool if, instead of HTML, they generated PHP which, in turn, pulled in DokuWiki pages along side generated function / call definitions. For example the XREF docs for the DokuWiki auth_login function contains a static description written by the developer. Below that would be great to have a section of dynamic content pulled from a DokuWiki page.

A rough guess at what would be involved.

• Modify the API doc generation to output the code which pulls in the correct DokuWiki page (using the function / class name as the $ID. Both phpDocumentor and phpXref use templates so this may be the best place to embed this.
• Provide some kind of “standalone” interface to DokuWiki that allows people to display a page embedded inside something else. Right now could probably be done just using the parser.php script but could be could to have a clean point of access.

PHP Documentor has a class, Converter, designed to output its internal data structures. Converter seems very flexible and it seems like it would be possible to implement a Converter subclass that would generate wiki markup instead of HTML. Converter was designed to be extended in just this manner. There is also a greater than average amount of documentation on the Converter class at the phpDocumentor site.

Been having a look at what's involved to write your own subclass of Converter and right now get the feeling it would be alot of work with phpDocumentor and that there's a steep learning curve involved. The experience got me looking at PHPDoctor. Again that's not perfect but the code base it much smaller and get the feeling there may be less work via this path.

Better news - there's a second generation of PHPDoctor in the CVS here - looks alot better. Should be pretty easy to add a Dokuwiki syntax generator

In fact, phpDocumentor has support in the Converter parent class for converting markup inside Doc Blocks, such as <B></B> into other formats (say ** **).

The converter is also responsible for determining which pages to output, their directory and file names. The converter could be modified to merge its files directly into the wiki data directory, perhaps into an api namespace.

I would recommend creating a standard section heading structure for each api page. The heading structure would demarcate areas for generated documentation and areas for manual documentation.

When the Converter went to write a file into DokuWiki's directory, it would first check and see if the file already existed. If not, it would write a file with the standard section format and the automatically generated information.

If a file already existed, then it would examine it for the standard structure. If the standard structure did not exist, then the Converter would move the file into the attic and write a new file, just as if the file hadn't been there.

If the file exists and the section headings match the standard structure, then the Converter would replace the information in the designated sections with the automatically generated documentation. If this made the page different than its original version, then the original would be moved to the attic and the new, merged version would be written to the data directory.

The Converter would keep track of all the files that it had written over the course of its documentation generation run. At the end, it would compare its list to the contents of the data directory. If any files existed in the data directory that were not generated, this means that the element was removed from the current version of the program. The Converter would then move these files to the archive, effectively deleting them from the wiki.

The list of changed, added, and deleted files would be added to the wiki's recent changes log.

Because of the use of the attic, in this scheme, no user entered information would ever be lost. The available pages in the wiki would always match the current version of the program. Users would be able to freely embellish the API documentation.

There are many many php projects using phpDocumentor. I believe that this combination would a killer application for DokuWiki, truly earning the name.

phpDocumentor already has Converters to output to CHM format, HTML, HTML with frames, PDF and XMLDoc. There are plenty of examples and the Converters seem self contained. Why not a Converter for DokuWiki markup? This is not a trivial project, but it is not as big as one might think.

Great to have, but hard to implement, would be the ability to mark wiki pages as being out of date when the function / class they refer to has been changed.

In reality that might involve something like;

• The doc gen tool needs to keep a copy of the source code it scans, for “diffs” with the next time it's executed. [Doesn't really need a whole copy? Just needs a signature of the class/function/method.]
• On next execution, the doc gen tool needs to diff the source against the last execution and identify a list of changes
• Given the list of changes (the line number being the key identifier) in, say, unified diff format, the doc gen tool then needs to identify which classes / functions in the source are effected by the change. In PHP that should be possible using token_get_all although for phpXref (written in Perl) it will need a CLI PHP script it can access the PHP tokenizer with.
• Knowing which functions / classes changed, “TAG” the corresponding wiki pages in a way the indentifies that page is out of date, perhaps using a special Edit Summary and a warning on the page that says it may contain outdated information.rr