Programming With Yii: Generating Documentation

Final product image — What You'll Be Creating

In this Programming With Yii2 series, I'm guiding readers in use of the Yii2 Framework for PHP. You may also be interested in my Introduction to the Yii Framework, which reviews the benefits of Yii and includes an overview of what's new in Yii 2.x.

Welcome! Recently, I wrote about building REST APIs for your Yii application and expanded custom APIs for our startup series application, Meeting Planner.

In today's tutorial, I'll introduce you to Yii's apidoc extension, which automatically generates browsable documentation for your code. I'm going to use it to generate API documentation for Meeting Planner.

Getting Started

Programming With Yii - APIdoc installation Guide

Installing apidoc is easy. As shown above, you just add the package using composer.

In addition to generating documentation from code, it's also capable of generating documentation from markdown and transforming this into PDFs.

For example, there is Yii Framework documentation, typical code documentation:

Programming With Yii - Auto-Generated Framework Documentation

And, here is the Yii2 Guide, which I believe is generated from markdown here and integrated with the code documentation for easy browsing:

Programming With Yii Generating Documentation - Guide generated from Markdown

Here's the documentation syntax that apidoc supports; it's based on phpdoc.

Ironically, the documentation for apidoc isn't yet complete, but it's fairly easy to use for basic auto-documentation.

Generating API Documentation

If you've followed along with my startup series, you're aware I'm building an extensive API to support mobile apps, etc. Apidoc is the ideal way for me to maintain dynamic automated documentation for it.

Certainly there are lots of other web services that help you document your API, but I found that Yii's apidoc worked well for my needs, and I appreciated the phpdoc-style theme they use.

Using a standard commenting style makes it likely that other services will be able to easily build documentation from Meeting Planner code if I ever wish to use them.

Creating Comment Blocks

Basically, you create comments within your code that apidoc uses to build your documentation. It's described within the Yii coding style guide.

You place a comment block at the top of each file like this one:

<?php
/**
 * @link https://meetingplanner.io
 * @copyright Copyright (c) 2016 Lookahead Consulting
 * @license https://github.com/newscloud/mp/blob/master/LICENSE
 */

And you place a comment block above each controller or model definition:

/**
 * UserTokenController provides API functionality for registration, delete and verify
 *
 * @author Jeff Reifman <jeff@meetingplanner.io>
 * @since 0.1
 */
class UserTokenController extends Controller
{

Then, you place a detailed comment block above each method, which includes parameters, return values, and exceptions:

/**
     * Register a new user with an external social Oauth_token
     *
     * @param string $signature the hash generated with app_secret
     * @param string $app_id in header, the shared secret application id
     * @param string $email in header, email address
     * @param string $firstname in header, first name
     * @param string $lastname in header, last name
     * @param string $oauth_token in header, the token returned from Facebook during OAuth for this user
     * @param string $source in header, the source that the $oauth_token is from e.g. 'facebook' e.g. [$oauth_token]
     * @return obj $identityObj with user_id and user_token
     * @throws Exception not yet implemented
     */
    public function actionRegister($signature,$app_id='',$email='',$firstname ='',$lastname='',$oauth_token='',$source='') {

You must follow the prescribed layout as described to feed apidoc successfully.

Using Placeholder Arguments for API Documentation

The Yii team developed apidoc to generate code documentation. However, as I wrote about in Securing Your API, all but the hash signature argument has been moved to http headers. These are invisible to apidoc. Thus, to generate API documentation, I decided to use a workaround.

As you can see, I include dummy arguments in the methods and then specify in the comments that these are sent as headers or "in header."

* @param string $signature the hash generated with app_secret
* @param string $app_id in header, the shared secret application id
* @param string $email in header, email address
* @param string $firstname in header, first name
* @param string $lastname in header, last name

As long as default values are included in the function definitions, there's no real harm done:

1	public function actionRegister($signature,$app_id='',$email='',$firstname ='',
2	$lastname='',$oauth_token='',$source='') {

In a moment, you'll see how this generally works for API documentation, even if it's not optimal coding style.

Let's move on to actually using apidoc to generate the documentation.

Generating the Documentation

You can review apidoc commands by running it without arguments:

$ ./vendor/bin/apidoc

This is Yii version 2.0.10.

The following commands are available:

- api                      Generate class API documentation.
    api/index (default)    Renders API documentation files

- guide                    This command can render documentation stored as
                           markdown files such as the yii guide
    guide/index (default)  Renders API documentation files

- help                     Provides help information about console commands.
    help/index (default)   Displays available commands or the detailed
                           information


To see the help of each command, enter:

  apidoc help <command-name>

I'll use the api option, and here are the configurations you can make:

$ ./vendor/bin/apidoc help api

DESCRIPTION

Renders API documentation files


USAGE

apidoc api <sourceDirs> <targetDir> [...options...]

- sourceDirs (required): array
  $sourceDirs

- targetDir (required): string
  $targetDir


OPTIONS

--appconfig: string
  custom application configuration file path.
  If not set, default application configuration is used.

--color: boolean, 0 or 1
  whether to enable ANSI color in the output.
  If not set, ANSI color will only be enabled for terminals that support it.

--exclude: string|array
  files to exclude.

--guide: string
  url to where the guide files are located

--guidePrefix: string (defaults to 'guide-')
  prefix to prepend to all guide file names.

--help, -h: boolean, 0 or 1
  whether to display help information about current command.

--interactive: boolean, 0 or 1 (defaults to 1)
  whether to run the command interactively.

--pageTitle: string
  page title

--template: string (defaults to 'bootstrap')
  template to use for rendering

To generate my API documentation, whose directory is also api, I'll do the following:

$ ./vendor/bin/apidoc api api api/web/docs 
    --pageTitle=MeetingPlanner
TargetDirectory already exists. Overwrite? (yes|no) [yes]:yes
Searching files to process... done.
Loading apidoc data from cache... done.
Checking for updated files... done.
8 files to update.
Processing files... done.
Updating cross references and backlinks... done.
Rendering files: done.
generating extension index files...done.
generating search index...done.
35 errors have been logged to api/web/docs/errors.txt
214 warnings have been logged to api/web/docs/warnings.txt

Because I haven't finished commenting the entire tree, there are errors and warnings generated. They most often look something like this:

Array
(
    [0] => Array
        (
            [line] => 31
            [file] => api/controllers/ParticipantController.php
            [message] => Method behaviors has no parent to inherit from in api\controllers\ParticipantController.
        )

    [1] => Array
        (
            [line] => 32
            [file] => api/controllers/PlaceController.php
            [message] => Method behaviors has no parent to inherit from in api\controllers\PlaceController.
        )

Browsing the Documentation

Publishing the documentation in the above apidoc command line to /api/web/docs means that you can browse the Meeting Planner documentation from the web.

For example, here's the UserTokenController:

Programming With Yii Generating Documentation - UserTokenController Example

Here is the actionRegister() method showing the parameter comments reflected with the in header information.

Programming With Yii Generating Documentation - UserTokenController Example actionRegister method

Here's the MeetingController documentation:

Programming With Yii Generating Documentation - MeetingController Example

And, here is the actionMeetingplacechoices() method:

Programming With Yii Generating Documentation - MeetingController Example actionMeetingplaces example

As you can see, this is extremely useful for sharing an API with third-party programmers in real time as you deliver the code. The great benefit is that it eliminates the need to manually maintain API documentation separately.

Anytime you can eliminate a task for a startup, it's a huge win.

Looking Ahead

I hope that you've seen a bit of the power of Yii2's apidoc extension. You can use it to maintain documentation for all your code, and also it encourages you to keep up with comments, which I'll do more of now.

If you have any questions or feedback, please post them in the comments. If you'd like to keep up on my future Envato Tuts+ tutorials and other series, please visit my instructor page or follow @reifman. Definitely check out my startup series and Meeting Planner.