Documenting code in phpDoc for Laravel 4

Question

I would like to document only the code that I have written in phpDoc. I am using Laravel 4 as my underlying MVC framework. What would be the a good way to structure the code so that I am able to document my code along with all the calling routines (for instance, routes.php) in the documentation. As it would be obvious, I will not want to document the whole MVC architecture inside Laravel.

Also, is it possible to document function calls in phpDoc?

Answer 1

phpDoc can be used anytime in anywhere, specially for OOP.

When we talk about OOP we call function as methods, however, in MVC we normally call functions as actions. In any case you can follow this pattern:

<?php
/**
 * @method int sum($a, $b)
 * @license GPL
 * @license http://opensource.org/licenses/gpl-license.php GNU Public License
 * @author Your Name <[email protected]>
 */
 class Calc
 {
    /**
     * Sums the first value with the second value
     *
     * @param  int|float $a //First Param
     * @param  int|float $b //Second Param
     * @example echo sum(2, 3); //returns 5
     * @since 1.1 //Version
     * @return int|float $result //Value Returned (use void if doesn't return)
     */
     public function sum($a, $b)
     {
         /**
          * @todo Needs implement validation
          */

         return $result = $a + $b;
     }
}

If you want to use on functions, you follow the same pattern:

/**
 * Returns Hello, $name
 *
 * @param string $name
 */
function hello($name) {
{
     printf('Hello, %s', $name);
}

The Routes of Laravel uses anonymous functions, similar to jQuery, however, you should be able to use PhpDoc also:

/**
 * Route for user
 *
 * @uses Route::get()
 * @example http://url.com/user/john
 * @param string $name
 */
Route::get('user/{name?}', function($name = 'John')
{
    return $name;
});

A more documented way, could be giving a name for your function and calling later on:

/**
 * Route for user
 *
 * @uses Route::get()
 * @example http://url.com/user/john
 * @param string $name
 */
function route_user_name($name = 'John')
{
    return $name;
});

Route::get('user/{name?}', route_user_name($name));

Check more in the Official website: http://www.phpdoc.org/

PS: Most of IDEs or Text Editors have plugin(extension) to make easy as the one for Sublime Text: https://github.com/SublimeText/PhpDoc