DocBlock en PHPDoc

Conforme va creciendo una aplicación, se va complicando el manejo del proyecto, por ejemplo para que sirva cada clase, cada método, cada atributo, y no solo para el desarrollador, sino para todos los colaboradores  y así ellos puedan entender partes del código sin necesidad de analizar el código línea a línea.

¿Qué es PHPDoc?

Wikipedia dice: es una adaptación de javadoc para php que define un estándar oficial para comentar código php, con las siguientes características:

• Hace comentarios que pueda leerse en un método estándar para animar a los programadores a definir y comentar los aspectos del código que normalmente se ignoran.

• Permite que los generadores de documentos externos como phpDocumentor puedan crear la documentación API en buen formato y fácil de entender.

• Permite que algunos IDEs como Zend Studio, NetBeans y Aptana Studio interpreten los tipos de variables y otras ambigüedades en el lenguaje de programación.

DocBlock

Son bloques de comentarios y se suelen incluir aunque no obligatoriamente antes de require, include, class, interface, trait, function, property, constant y variables.

Cada DocBlock comienzan con /** (doble asterisco) y terminan */, y en cada línea hay que añadir *.

Partes de un DocBlock

1. Descripción corta: pequeña descripción no mayor a 80 caracteres, más conocido como título, es obligatorio.
2. Descripción larga: descripción completa de lo que hace el código.
3. @tags etiquetas que representan información específica de una gran lista de tipos y tags, como @author, @param, @return, entre otros.

Mis archivos tienen la siguiente estructura:

<?php

/**
 * Archivo core/Peticion.php
 * 
 * @copyright (c) 2015, KintuCms
 * @author Edison Ataucusi R. <eataucusi@gmail.com>
 * @license http://creativecommons.org/licenses/by-nc-sa/4.0/ CC BY-NC-SA 4.0
 */

/**
 * Administra las rutas o peticiones
 * 
 * Las peticiones a la aplicación se hace de la forma
 * "controlador/método/param1/param2/..../paramN", y esta clase se encarga del
 * manejo de estas peticiones, extrae el controlador y el método y agrupa los
 * parámetros en un arreglo.
 */
class Peticion {

    /**
     * @var string Controlador de la petición 
     */
    public static $controlador;

    /**
     * @var string Método de la petición 
     */
    public static $metodo;

    /**
     * @var array Parámetros de la petición 
     */
    public static $args;

    /**
     * @var string Url saneado de la petición 
     */
    private static $url;

    /**
     * Obtiene las partes de la petición
     * 
     * Extrae el controlador y el método de la petición, si el controlador o
     * método no existe se les asigna un controlador y método por defecto 
     * denominado index; también agrupa los parámetros en un arreglo, si 
     * no existen parámetros se asigna un arreglo vacío.
     */
    public static function rutear() {
        if (!is_null(filter_input(INPUT_GET, 'url'))) {
            self::$url = filter_input(INPUT_GET, 'url', FILTER_SANITIZE_URL);

            $_aux = array_filter(explode('/', self::$url));
            self::$controlador = strtolower(array_shift($_aux));
            self::$metodo = strtolower(array_shift($_aux));
            self::$args = $_aux;

            if (empty(self::$metodo)) {
                self::$metodo = 'index';
            }
        } else {
            self::$controlador = 'index';
            self::$metodo = 'index';
            self::$args = array();
        }
    }

    /**
     * Obtiene el método de la petición
     * 
     * Une el prefijo al método de la petición 
     * @param string $prefijo Cadena prefijo
     * @return string Método a ejecutar
     */
    public static function getMetodo($prefijo = "") {
        return $prefijo . self::$metodo;
    }

}

El primer DocBlock es la perteneciente al archivo, y el segundo DocBlock pertenece a la  clase.