• Divers
  • Livres
• Computing
  • Tools
    • phpSimpleDoc
      • User Guide
      • Inside the code
  • PHP
  • Spip
  • Zend Framework
• Approches
  • Astronomie
    • Télescope
  • Statistiques
• Famille
  • Philippe Graff
    • Architecture et urbanisme
    • Géophysique et astrophysique
  • Pierre Graff
• Nature
  • Vautours
• Pratique
  • Yourte
    • Plans de la yourte
    • Chantier yourte

 Main Sequence

index.php

A documentation run starts in index.php
index.php contains 2 parts :

- A part to list the available user commands, corresponding to .ini files located under phpsimpledoc/user directory.
This part is used only if phpSimpleDoc is called from the web interface, without GET or POST.

- A part to order documentation generation
This part is used when phpSimpleDoc is called from the web interface or from the command line.
This part is activated when index.php is called :
- with a GET or POST 'command' variable (when called from web interface).
- with a parameter (when called from command line).

Main sequence

Documentation generation involves the following steps :

• User command file is first parsed, and contains the raw instructions.
• Bootstrap::init() is called ; it mainly loads the application configuration file (src/app/config.app.ini), containing rules for class naming convention
• Static method Documentor::generateDocumentation($userConfig) is called
• generateDocumentation() calls a factory method, Documentor::getInstance($userConfig), which creates a subclass of Documentor, depending on $userConfig['documentorType'] (for ex. an instance of deDocumentor for default generator).
• The subclass' constructor creates appropriate instances of Helpers, and put them in an array (Documentor->$helpers).
• Documentor::generateDocumentation($userConfig) goes on and just calls helpers' action() method.

This corresponds to a strategy pattern : the executed code is selected at runtime. What is called helpers here are often called behaviours in litterature.

Helpers

A helper is : a class performing part of the documentation job.
Helpers inherit from abstract class Helper, which provides :
- a field $docu, to access to the Documentor which conducts the run ;
- "magic" __get, __set and __isset, to shorten the syntax : $this->classes instead of $this->docu->data['classes']
- an abstract method, action() that suclasses must implement.

So most of the job is done by helpers. Documentor is conducting the whole process, and is used as a central repository containng all the data computed and needed by helpers.
Helpers don't store any data, or just auxiliary variables helping them to do their job. Instead, helpers fill and use documentor's public fields (ex : $userConfig, $data).
Helper's definition is vague, so there are several kinds of helpers, of different roles and importance ; they are just objects that permit object composition.

Steps to document

In the default documentor, the process of generating code documentation was decomposed in different steps :

1. Loading configuration
2. Computing files and directories to document
3. Loading code and computing data structures ; described in Parsing PHP Code
4. Generating the output directories
5. Generating the contents of pages
6. Generating the pages
7. Reporting the eventual problems that occured during the run

For each step, an asbtract subclass of helper was defined, giving this hierarchy :

In a strict programming point of view, these helpers are useless, they just provide an other name for method action(), but they permit to render the code more readable.
All documentor implementations do not necessarily use all these helpers ; for example, in 'php' documentor implementation, step 2 doesn't exist.

Secondary helpers

Some steps listed above can be decomposed in sub-steps. For example, contents generation involves several different types of contents ; each type of contents is handled by one helper. So the ContentsGenerator implementation is just coordinating contents generation, calling for sub-helpers which perform the effective generation.

Configuration files

Each run of phpSimpleDoc needs 3 configuration files :

• User config : (ex : user-apis/phpSimpleDoc.ini) the user indicates what code to document and what documentation should be generated
• Engine config : (ex : src/engines/default/config.default.ini) contains the default values for optional fields of user config
• Application config (src/app/config.app.ini) contains rules used by autoload (see Naming conventions)