Parsing the source

Phase 1 of the Documentation Generation Process is for DocBlox to analyze your existing source code and create a summary of its structure.

You can invoke DocBlox to generate this structure summary using two different ways executables:

1. docblox.php
2. parse.php

Both of these executables are located in the bin directory of your DocBlox installation path, and when you install using PEAR you can invoke the docblox command from any location on your operating system.

DocBlox.php

The docblox command (which actually executes the docblox.php file in the aforementioned bin folder) is a forefront which can be used to indirectly invoke the parse.php executable. This was done to simplify things for use in Continuous Integration environments like Jenkins as they commonly require a single global executable file.

So. what does all that mean?

Every time you invoke the docblox(.php) command with the term parse as its first argument; it will actually invoke parse.php. As such we will only describe parse.php and its arguments.

Note: docblox.php is planned for an overhaul; the intention in the end is that this executable will invoke both the parsing and transformation in one go; currently you need to invoke this script twice separately to achieve a complete generation of your API documentation.

Parse.php

The CLI interface of the parser was originally designed to match the CLI interface of phpDocumentor. This was done to make the migration from phpDocumentor to DocBlox easier.

As such the parser always requires that you provide it with files and directories to parse using either the command line parameters or the configuration file.

Command line parameters

Currently the parser supports the following command line parameters:

Configuration file

If you have read the command line paragraph well you have discovered that DocBlox also supports configuration files which define what settings are used. This is especially useful when you have a large project with specific settings that you do not want to type by hand every time; additionally it is possible to provide more options to the parsing process then the command line can offer.

DocBlox has 3 layers of configuration:

1. Global configuration; this is defined in the docblox.config.xml file in the root of the DocBlox application folder. This file contains the defaults for the entire application and thus contains every configuration setting that DocBlox supports. Please remember that this file is distributed with DocBlox and can change during an upgrade.
2. Per-project configuration; this is an XML file which is supplied using the -c command line directive. This file is merged with the global configuration (with the settings here taking precedence) and the combined settings are used. The per-project configuration does not need to contain all elements that are in the global configuration. Only the elements where an actual change is appropriate.
3. Command line directives; each directive on the command line overwrites a setting in the global and per project configuration and is thus final.

This mechanism provides a strong basis for flexible configuration as each layer refines and builds on the previous.

The global configuration file (version 0.8.7):

<?xml version="1.0" encoding="UTF-8" ?>
<docblox>
  <target>output</target>
  <extensions>
    <extension>php</extension>
    <extension>php3</extension>
    <extension>phtml</extension>
  </extensions>
  <logging>
    <level>warn</level>
    <paths>
      <default>{APP_ROOT}/log/{DATE}.log</default>
      <errors>{APP_ROOT}/log/{DATE}.errors.log</errors>
    </paths>
  </logging>
  <markers>
    <item>TODO</item>
    <item>FIXME</item>
  </markers>
  <transformations>
    <template name="default" />
  </transformations>
</docblox>

Except for the logging element and the transformations element everything should be reasonably self-explanatory (if not; hop on the Freenode IRC server, join #docblox and ask).

Logging

There is no command line argument which is equivalent to the settings in this element; so I will explain the elements contained here:

• level; this is the minimum level that will be logged. Everything below this level will be ignored and not recorded.
  I would like to point out here that it is currently not possible to actually disable logging; if you want to log as little as possible I can advice to set the setting to emerg as that is only rarely used.
  The applicable levels are (in order):
  • debug
  • info
  • notice
  • warn
  • err
  • crit
  • alert
  • emerg
• paths->default; this is the location of the normal logging file; it may contain 2 parameters: {APP_ROOT} and {DATE}, the first is the location of the DocBlox installation folder and the second is the current time formatted as: YmdHis
• paths->errors; this is the location where everything concerning debugging is stored when verbose mode is on.

Transformations

Here you can add individual transformations and / or templates. This subject not entirely into scope for this part of the documentation and will be discussed in the transformation section.

Examples

The minimal command line argument is where you tell DocBlox to parse the current directory and create a structure.xml in the subfolder output of the current working directory (we will also show the docblox command as extra example):

$ php bin/parse.php -d .
$ docblox parse -d .

When you want to tell docblox to store the structure.xml file in your home directory you can do the following:

$ php bin/parse -d . -t ~
$ docblox parse -d . -t ~

Ignoring any file in the tests sub-folder goes like this:

$ php bin/parse -d . -t ~ -i tests/*
$ docblox parse -d . -t ~ -i tests/*