Пример комментариев для phpDoc

PhpDocumentator - это средство, позволяющее автоматически генерировать документацию на код, основываясь на комментариях.

Для этого используется специальный вид комментариев:
/**
 * Комментарий
 */
Пример использования комментариев для phpDoc:
/**
 * Файл с классом по работе с базой данных,
 * используется для демонстрации возможнойстей phpDoc,
 * поэтому комментарии используются в избытке
 * 
 * @author Вася Пупкин <pupkin@mail.com>
 * @copyright 2001-20011 Вася Пупкин
 * @license http://www.opensource.org/licenses/lgpl-license.php LGPL
 * @version 1.0
 * @package Имя_пакета
 * @link http://www.css.kiev.ua
 * @todo Сделать класс максимально настраиваемым
 */
/**
 * Пример класса для работы с БД
 */
class Singleton {
    
    /** @var Singleton Экземпляр класса */
    private static $_instance; // По умолчанию приватные члены и методы класса не документируются!
    
    /** @var PDO Идентификатор соединения с БД */
    private static $_db;
    
    /**
     * Защищаем класс от создания через конструктор, сохраняем в члене класса {@link $db} объект PDO
     * @return void
     * @todo Сделать параметры соединения настраиваемыми
     */
    private function __construct(){
        // Подключаемся к БД
        try {
            self::$_db = new PDO(
                'mysql:host=localhost;dbname=database',
                'username',
                'password',
                null
            );
        } catch(PDOException $e) {
            echo 'PDO error: ' . $e->getMessage();
        }
    }
    
    /**
     * Защищаем класс от создания через клонирование, метод не будет задокументирован
     * @ignore
     */
    private function __clone() {}
    
    // Защищаем класс от создания через unserialize, метод не будет задокументирован
    private function __wakeup() {}
 
    /**
     * Функция возвращает единственный экземпляр класса
     * @return Singleton
     */
    public static function getInstance() {
        if (is_null(self::$_instance)) {
            self::$_instance = new self();
        }
        return self::$_instance;
    }
    
    /**
     * Функция выполняет запросы к БД
     * @param string $statement SQL выражение, которое необходимо выполнить
     * @param array $driver_options Атрибуты для подготовки SQL выражения
     * @return PDOStatement
     */
    public function prepare($statement, $driver_options = array()) {
        return self::$_db->prepare($statement, $driver_options);
    }
}

// Пример использования
$TestObject = Singleton::getInstance();
$st = $TestObject->prepare('SELECT * FROM `table`');
$st->execute();
// ...

Метки: ,

Оставить комментарий

Вы должны авторизоваться для отправки комментария.