meeting controller

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:

Leave a Comment

Scroll to Top