Documentation with phpDocumentor: Part 2

Packt Publishing

Proven enterprise development tools and best practices for designing, coding, testing, and deploying PHP applications

Documentation without DocBlocks

You have probably already noticed that short of some inline comments, the sample project has no DocBlocks, tags, or anything else added by the programmer for the purpose of documenting the code. Nevertheless, there is quite a bit that phpDocumentor can do with uncommented PHP code. If we are in the directory containing the project directory, we can run phpDocumentor and ask to generate documentation for the project like this:

The above command will recursively process all files in the project directory (--directory ./project/), create documentation with a custom title (--title 'Generated Documentation - No DocBlocks'), include a source code listing of each file processed (--sourcecode on), save all documentation to the docs directory (--target ./project/docs), and group everything under a specified package name (--defaultpackagename 'UserAuthentication').

Listing all documentation pages that phpDocumentor generated is impractical, but let's take a look at the outline and at least one of the classes. All we have to do to view the documentation is to open the index.html file in the docs directory where we told phpDocumentor to direct the output with a web browser.

Looking at the above screenshot, we see that phpDocumentor correctly found all the class files. Moreover, it identified Accountable as an interface and found index.php, even though it contains no class definitions. All classes and interfaces are grouped together under the AuthenticationUser package name that was specified from the command line. At the same time, we see some of the shortcomings. There is no further classification or grouping and all components are simply listed under the root level.

Before we move on, let's also take a look at what information phpDocumentor was able to extract from the Users.php file:

It correctly identified the methods of the class, their visibility, and which parameters are required. I think that is a pretty useful start, albeit the description is a bit sparse and we have no idea what methods were actually implemented using the magic __call() method.

Another point to note here is that the class property $accounts does not appear in the documentation at all. That is intended behavior because the property has been declared private. If you want elements with private visibility to appear in your documentation, you will have to add the –pp / --parse private command line option or put this option in a config file.

Documentation with DocBlocks

Of course, this example wouldn't be complete if we didn't proceed to add proper DocBlocks to our code. The following is the exact same code as before, but this time it has been properly marked up with DocBlocks.

Since none of the functionality of the code has changed, we can skip that discussion here. What has changed, however, is that we have added DocBlocks for each file, class, interface, method, and property. Whereas the version of the project without documentation had a total of 113 lines of code, the new version including DocBlocks has 327 lines. The number of lines almost tripled! But don't be intimidated. Creating DocBlocks doesn't take nearly as much time as coding. Once you are used to the syntax, it becomes second nature. My estimate is that documenting takes about 10 to 20 percent of the time it takes to code. Moreover, there are tools to really speed things up and help you with the syntax, such as a properly configured code editor or IDE.

Now let's see how phpDocumentor fared with the revised version of the project. Here is the index page:

This time, the heading shows that we are looking at the Web Services package. Furthermore, the classes and interfaces have been grouped by sub-packages in the left-hand index column. Next, here is the documentation page for the Users class:

As you can see, this documentation page is quite a bit more informative than the earlier version. For starters, it has a description of what the class does. Similarly, both methods have a description. All the tags and their content are listed and there are helpful links to other parts of the documentation. And, from the method tag we can actually tell that the magic method __call() was used to implement a method of the form validate<user>($password). That is quite an improvement, I would say!

To really appreciate how much more informative and practical the documentation has become by adding DocBlocks, you really need to run through this example yourself and browse through the resulting documentation.

phpDocumentor options

There are a good number of options when running phpDocumentor that affect everything from where it looks for the code to parse, how to parse, what kind of output to generate, and how to format it. All the options are available from both the command line and the web-based interface.

Command line reference

Here is a listing of all command line options supported by phpDocumentor 1.4.2, which is the version that was used while writing this article. The descriptions are taken directly from the output produced by running phpdoc --help from the command line and it is only reproduced here for the readers' convenience.

Short option

Long option

Description

-f

--filename

Name of file(s) to parse ',' file1,file2. Can contain complete path and * ? wildcards.

-d

--directory

Name of a directory(s) to parse directory1,directory2

-ed

--examplesdir

Full path of the directory to look for example files from @example tags

-tb

--templatebase

Base location of all templates for this parse.

-t

--target

Path where to save the generated files

-i

--ignore

File(s) that will be ignored, multiple separated by ','. Wildcards * and ? are ok

-is

--ignoresymlinks

Ignore symlinks to other files or directories, default is off

-it

--ignore-tags

Tags to ignore for this parse. @package, @subpackage, @access and @ignore may not be ignored.

-dh

--hidden

Set equal to on (-dh on) to descend into hidden directories (directories starting with '.'), default is off

-q

--quiet

Do not display parsing/conversion messages.

Useful for cron jobs on/off, default off

-ue

--undocumentedments

Control whether or not warnings will be shown for undocumented elements. Useful for identifying classes and methods that haven't yet been documented on/off default off

-ti

--title

Title of generated documentation, default is 'Generated Documentation'

-h

--help

Show this help message

-c

--useconfig

Use a Config file in the users/ subdirectory for all command-line options

-pp

--parseprivate

Parse @internal and elements marked private with @access. Use on/off, default off

-po

--packageoutput

Output documentation only for selected packages. Use a comma-delimited list

-dn

--defaultpackagename

Name to use for the default package. If not specified, uses 'default'

-dc

--defaultcategoryname

Name to use for the default category. If not specified, uses 'default'

-o

--output

Output information to use separated by ','. Format: output:converter:templatedir like "HTML:frames:phpedit"

-cp

--converterparams

Dynamic parameters for a converter, separate values with commas

-ct

--customtags

Custom tags, will be recognized and put in tags[] instead of unknowntags[]

Config files

Rather than having to specify all options you want on the command line each time you run generate documentation, phpDocumentor supports config files. You can put all your command line switches in one config file and then conveniently tell the phpdoc executable to use the config file. Here is a config file that has all the same options that we used in the above example:

;; phpDocumentor parse configuration file;;;; interface will automatically generate a list of .ini files that canbe used.;;;; project_phpdoc_config.ini is used to generate the documentation;; for the sample project in the chapter on phpDocumentor;;;; Copyright 2009, Dirk Merkel <dirk@waferthin.com>

[Parse Data];; title of all the documentation;; legal values: any stringtitle = Generated Documentation - No DocBlocks

;; where should the documentation be written?;; legal values: a legal pathtarget = /Users/dirk/php/project/docs

;; turn this option on if you want highlighted source code for everyfile;; legal values: on/offsourcecode = on

To use the config file from the command line, simply type: phpdoc –c /Users/dirk/php/project/project_phpdoc_config.ini

For additional examples of user-defined config files, consult the user/ directory of your phpDocumentor installation. There is also a system-wide default config file called phpDocumentor.ini that can be found in the top level of the phpDocumentor installation directory. It contains some additional options that are not accessible from the command line, such as toggling debug mode, which file extensions to parse, and so on.

Browser-based interface

You may remember from the installation, phpDocumentor includes a browser-based interface that gives you the same options as the command line. However, you get the added convenience of a tabbed interface that lets you easily explore the available options without having to consult the help section. Of course, you can also select your custom config file from this interface just as you did from the command line. Here is an example of the browser-based interface while processing the documentation for our sample project:

One of the 'gotchas' of working with the browser-based interface is that you must have all permissions properly set up. For example, if your project is residing in a directory outside your web server's DocumentRoot, phpDocumentor might not be able to read the files. Also, if the template you are using to format the output comes with one or more stylesheets that need to be copied to the output directory, your web server and/or PHP will need the necessary permissions.

Summary

If the example in this article did not sell you on the benefits of documenting your code using the phpDoc syntax, you only need to take a look at the API documentation of some of the biggest PHP projects out there, such as Zend Framework and Pear. There is a reason that this method of documenting source code has been around for over ten years. Programmers quickly get the big picture of how the various components come together. Moreover, it also allows them to drill down to the granular level of parameters, return values, and so on.

If you are not in the habit of commenting your code, I suggest you start slowly. Rather than documenting every single element, start with file and class-level DocBlocks. I suspect that you will quickly get used to creating documentation at the same time as code – especially when you see the results in the form of detailed and useful documentation. Hopefully, you will feel encouraged enough to start documenting more elements and produce documentation that any programmer that might come across your code can benefit from.

Alerts & Offers

Series & Level

We understand your time is important. Uniquely amongst the major publishers, we seek to develop and publish the broadest range of learning and information products on each technology. Every Packt product delivers a specific learning pathway, broadly defined by the Series type. This structured approach enables you to select the pathway which best suits your knowledge level, learning style and task objectives.

Learning

As a new user, these step-by-step tutorial guides will give you all the practical skills necessary to become competent and efficient.

Beginner's Guide

Friendly, informal tutorials that provide a practical introduction using examples, activities, and challenges.

Essentials

Fast paced, concentrated introductions showing the quickest way to put the tool to work in the real world.

Cookbook

A collection of practical self-contained recipes that all users of the technology will find useful for building more powerful and reliable systems.

Blueprints

Guides you through the most common types of project you'll encounter, giving you end-to-end guidance on how to build your specific solution quickly and reliably.

Mastering

Take your skills to the next level with advanced tutorials that will give you confidence to master the tool's most powerful features.

Starting

Accessible to readers adopting the topic, these titles get you into the tool or technology so that you can become an effective user.

Progressing

Building on core skills you already have, these titles share solutions and expertise so you become a highly productive power user.