phpDocumentor

Application Flow

Introduction

Generating the documentation for a project involves a fair number of steps but can be best summarized with this Activity Diagram.

Boot the applicationParse files into an ASTTransform AST into artifacts
testMain program flow

This three step process enables phpDocumentor to break down a project into its most basic components, called Structural Elements, and depending on which template was selected generate various types of output.

An example of such output may be a website that documents the project's internal API. Another example could be a checkstyle XML document that describes which errors in the project's DocBlocks were found. Anything is possible.

In this document I provide an overview of all moving parts in the application but do not explain each technical term in-depth.

The flow in more detail

The complete application flow is perhaps best described with the Activity Diagram below. It should cover most of the large activities that occur in the application, including when and which events are emitted. This Activity Diagram does not include detailed activities such as logging or translating.

Another thing to note is that the impact of Service Providers is not visible in this flow. That is not because Service Providers don't have their effect but because Service Providers blend in with the complete application flow and are mainly used to add writers, filters validators and other components that can are automatically used during the transformation process.

In the subchapters I will provide more detail on the individual sections and show the activities that are collapsed in this diagram (such as Boot the application, Add File Representation to Project and other activities that are surrounded by an additional border)

Boot the applicationParse files into an ASTSet parsing parametersFind project filesRemove stale items from Descriptor CacheLoad Descriptor CacheFile is cachedNoYesAdd File Representation to ProjectLoad Cached FileYesThere are unprocessed files?NoWrite partial texts to ProjectSave Cache to DiskTransform AST into artifactsLoad Cache From DiskLoad TemplatesLoad Transformations from TemplatesPass is "Transformer"Transform all filesPass is "Linker"Link FQSENs to DescriptorsExecute compiler pass specific behaviourFor each Compiler Pass

Boot the Application

Initialize dependencies using ApplicationLoad configurationAdd loggingRegister phpDocumentor's Service Providers

Parse files into an AST

The following Activity Diagram below is an excerpt from the Diagram at the beginning of the chapter and is repeated to support the text.

Set parsing parametersFind project filesLoad Descriptor CacheRemove stale items from Descriptor CacheFile is cached and cache is validYesNoLoad Cached FileAdd File Representation to ProjectYesThere are unprocessed files?NoWrite partial texts to ProjectSave Cache to Disk

In order to be able to properly generate documentation phpDocumentor needs to find all files in the project that you would want to document. There are several properties that influence which files are eligible for your documentation based on provided parameters and options, such as directories and a listing describing which files are ignored.

If the given target folder contains a cache of a previous run of phpDocumentor then this is loaded. phpDocumentor will remove all files from that cache that are not present in the file listing that was found earlier so that it doesn't contain any entries that are not intended to be documented.

Once that is done phpDocumentor should have a description of your Project, represented by an instance of the ProjectDescriptor class, that may be pre-populated with the Abstract Syntax Tree (other Descriptors) that were discovered during a previous run.

When phpDocumentor is ready to create, or actually refresh, the AST it will iterate over all files that were discovered. A hash is generated of each file and checked with the cache if this file is still fresh. Should the hash not exist in the Cache or it differs for a given file then phpDocumentor will create a new representation of that file and overwrite the previous one.

At this stage all links between elements, such as that of an @see tag, are still strings containing the FQSEN that references another element. It is not until much later, in the Linker, where the text references are converted into actual references to other objects.

This is done because:

  • caching references to objects can easily disconnect the two objects
  • if a file is refreshed then all links are lost and should be re-made
  • filtering and alterations may be done at later stages and actual references may become stale or new ones should be made.

Add File Representation to Project

Reflect fileCreate File representation as FileDescriptorMap reflected information onto new DescriptorFilter DescriptorValidate DescriptorAdd Element Descriptor to FileFor each Structural Element in FileAdd File representation to Project

Transform AST into artifacts

Transform all files

Emit event "transformer.transform.pre"Emit event "transformer.writer.initialization.pre"Boot involved writersEmit event "transformer.writer.initialization.post"Emit event "transformer.transformation.pre"Execute associated Writer and pass TransformationEmit event "transformer.transformation.pre"For each TransformationEmit event "transformer.transform.post"

Search results