There and Back Again

2.0 Converter Design

Walking back from the bookstore I had some really good ideas for the converter design in phpDocumentor 2.0

First the parser should ouput a flat tree of objects representing the code, we can use the php5 reflection classes for the design of this, im guessing will have to extend them a bit and add docblock access methods.

My main idea deals with howto manage template complexity it borrows a bit from the discussion surrounding the PEAR delegation class submission and howto allow base templates with overrides on the Savant list.

First the accessors on the objects representing your parsed code should always call an encode method. The default method will just return the data with no changes, but for HTML or XML output the encode method can be delegated to a utility class that takes care of there requirements. There should also be a helper class for each output type that does the standard stuff like create a link or a class tree. If these options can be made exteremly generic then you really only need 2 converters, the rest is templates and setup of the helper and delegated classes.

The 2 converter are of course a single file output converter and a multi-file output converter. Hmm maybe only one coverter with options for where to break out pages, Project,Package,Class,Page, etc. Then you just need to hand the class the template file match-up for the fileoutputs selected.

Also i think its a good idea to make the template engine a selectable option, and that when any engine that implements the same interface as Savant can be used.

Finally one of the biggest parts of converter complexity can be manage by using template inheiritance. The default style goes into a directory called shared. Then the template selected goes into another directory. The include path is set to first the selected templates dir and then the shared dir. That way to make a new template you only have to create new files for what you want to change.

This same approach can also be used for css files, only in this case we just use the cascading feature of css, you always include the base css files and then just add new ones for the specific template the override the base one.

The only big issue i see is the Frames no frames output, but i think that can be managed since you always have that nav code its just what file it goes into, would should be able to push that to a template choice with a little bit of thought.

Comments and code are of course always welcome.

One thought on “2.0 Converter Design

  1. Pingback: There and Back Again :: phpDocumentor 2.0 work