Prev Next

Writing a New Converter

Overview of how to write a new Converter

by Joshua Eichorn
[email protected]
by Gregory Beaver
[email protected]

Introduction to Converters

This documentation deals only with the advanced programming topic of creating a new output converter. To learn how to use phpDocumentor, read the phpDocumentor Guide to Creating Fantastic Documentation. To learn how to extend an existing Converter, read Converter Manual

Basic Concepts

Abstract Parsing Data

Source Code Elements

A Converter's job is to take abstract data from parsing and create documentation. What is the abstract data? phpDocumentor is capable of documenting tutorials, and a php file and its re-usable or structurally important contents. In other words, phpDocumentor can document:

phpDocumentor represents these PHP elements using classes:

This relationship between the source code and abstract data is quite clear, and very simple. The data members of each abstract representation correspond with the information needed to display the documentation. All PHP elements contain a DocBlock, and this is represented by a class as well, parserDocBlock. The elements of a DocBlock are simple:

phpDocumentor represents these elements using classes as well:

HTML-specific issues

There are some other issues that Converters solve. In HTML, a link is represented by an <a> tag, but in the PDF Converter, it is represented by a <c:ilink> tag. How can we handle both cases? Through another abstract class, the abstractLink and its descendants:

Note the absence of an "includeLink" class - this is intentional, as only re-usable elements need to be linked. An include statement is always attached to the file that it is in, and cannot be anywhere else.

These abstract linking classes contain the information necessary to differentiate between the location of any of the element's documentation. They are only used to allow linking to documentation, and not to source code. A link is then converted to the appropriate text representation for the output format by Converter::returnSee() (a href=link for html, c:ilink:link for pdf, link linkend=link in xml:docbook, and so on).

The other issues solved by a converter involves html in a DocBlock. To allow better documentation, html is allowed in DocBlocks to format the output. Unfortunately, this complicates output in other formats. To solve this issue, phpDocumentor also parses out all allowed HTML (see phpDocumentor Tutorial for more detailed information) into abstract structures:

is mapped to classes: <p> is represented by partitioning text into an array, where each array item is a new paragraph. (as in parserDocBlock::$processed_desc)

With these simple structures and a few methods to handle them, the process of writing a new converter is straightforward.

Separation of data from display formatting

phpDocumentor has been designed to keep as much formatting out of the source code as possible. For many converters, there need be no new code written to support the conversion, as all output-specific information can be placed in template files. However, the complexity of generating class trees does require the insertion of some code into the source, so at the bare minimum, the getRootTree() method must be overridden.

Methods that must be overridden

Creating a new converter can be challenging, but should not be too complicated. You need to override one data structure, Converter::$leftindex, to tell the Converter which of the individual element indexes your Converter will use. You will also need to override a few methods for the Converter to work. The most important relate to linking and output.

A Converter must override these core methods:

A Converter may optionally implement these abstract methods:

The following methods may need to be overridden for proper functionality, and are for advanced situations.

Converter methods an extended converter should use

Prev   Next
inline {@tutorial} Converter Default Template Variables

Documentation generated on Mon, 05 Dec 2011 21:24:22 -0600 by phpDocumentor 1.4.4