The following Activity Diagram below is an excerpt from the Diagram at the beginning of the chapter and is repeated to support the text.
Application Flow
Introduction
Generating the documentation for a project involves a fair number of steps but can be best summarized with this Activity Diagram.
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.
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 Application
Parse files into an AST
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.