Programming With Yii: Generating Documentation

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:

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

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

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."

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

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:

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

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

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

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.

Related Links

Source: Tuts Plus

About the Author