Создание документации на основе PhpDocumentor или немного про комментирование кода

PhpDocumentor автоматически генерирует из исходного кода документацию. Поэтому скрипт покажет лучший вариант только при правильном построении комментариев, именно это мы и разберем в первую очередь.

Описание функций, методов, файлов и переменных

Описание идёт таким образом:
/**
* Краткое описание
*
* Подробное описание
* которое возможно в несколько строк
*
* @тег значение
*/

Сразу пример, который далее мы немного разберём.

file1.php
<?php
/**
* Файл примера правильного документирования
*
* Здесь я постараюсь использовать
* максимально много тегов
* @author Lion__ <moderation@mail.ua>
* @version 1.0
* @package files
*/

/**
* Подключаем файл
*/
include_once 'file2.php';

/**
* Просто класс
* @package files
* @subpackage classes
*/
class Test2 extends Test {

/**
* Получение значения с {@link $data}
* @uses Test::data Переменная, с неё мы берём данные
* @return void
*/
function getdata()
{
$this->data = $data;
}
}
/**
* Тестовая переменная
*
* Дело в том что обычную переменную нельзя описать
* @global Test $GLOBALS['a']
* @name $a
*/
$GLOBALS['a'] = new Test;

/**
* Обычная функция
* @global Test показываем что мы используем глобальную переменную $a
* @staticvar string $var Эту переменную мы будем возвращать
* @param string $param1 Первый параметр функции
* @param string $param2 Второй параметр
* @return string
*/
function func($param1, $param2 = 'value')
{
static $var = 7;
global $a;
return $var;
}

/**
* Константа
*/
define('testing', 6);
?>

file2.php
<?php
/**
* Второй файл примера правильного документирования
*
* @author Lion__ <moderation@mail.ua>
* @version 1.0
* @package files
*/

/**
* Просто класс
* @package files
* @subpackage classes
*/
class Test {
/**
* Переменная хранящая значение типа integer
* @link _ttp://www.example.com Подробное описание. Вместо _ должно быть h
* @see setdata
* @access private
* @var integer
*/
var $data;

/**
* Установка значения
* @param integer $data Значение для установки в {@link $data}
* @uses Test::$data Для размещения данных
* @return void
*/
function setdata($data)
{
$this->data = $data;
}
}

Описание примера

Разбирать местоположение комментариев мы не будем, рассмотрим саму структуру.

• Краткое описание
• Полное описание. Может использоваться по желанию
• Теги

С первым и вторым всё ясно. С третьем давайте подробнее.

@package Название
Логически объединяет файлы, классы, методы и тд. Долно быть сделано с умом или вообще не сделано. В PhpDocumentor возможно потом просматривать подобно категориям на сайте

@subpackage Название
Аналогично>return, но действует как подгруппа.

global [private | protected | public]
Доступ к элементу

access Текст
Автор элемента

version Текст
Версия

copyright Текст
Копирайты. Думаю всё ясно.

@category Название
Используется для организации групп. Полезно если портируете в XML формат, иначе смысла нет.

example Сылка|Путь
Ссылка или путь на пример работы

author тип $переменная
Наверное самый интересный тег. Дело в том что PhpDocumentor не анализирует глобальные переменные, этим тегом мы их задаём вручную. В примере можно увидеть как они задаются, и используются( функция func )

global
Игнорирование элемента. Иногда удобно.

@license Url
Ссылка на лицензию

link URL Описание ссылка
Формирование ссылки

see Тип Описание
Используется только для переменных класса

name $Имя
Используется в связки с>@ignore. Для идентификации.

param Тип $переменная Описание
Параметр, как объяснить не знаю, смотрите пример. Тип может быть любой: тип PHP, имя класса, или mixed

@package Тип
Тип возвращаемой ф-цией. Если ничего не возвращает прописывается void

var file.ext|elementname|class::methodname()|class::$variablename|functionname()|functionname
Формирует ссылку на объект который указан


Иногда в функциях мы задаём статические переменные. Этот тег служит для их описания

todo Текст
Используется для описание идей которые ещё небыли воплощены в реальность.

uses file.ext|elementname|class::methodname()|class::$variablename|functionname()|functionname
Аналогичен see. Или я просто не увидел различия…

Так же хотел отметить что в описаниях возможно использовать теги example, tutorial, link. Задаются они так: {@тег параметр}

Вот и всё… С комментариями разобрались, можно приступать к создании документации.

Создание документации

Переходим сюда и качаем PhpDocumentor.

Распаковываем.

Открываем phpdoc.bat:
Находим:
SET phpCli=
Путь заменяем на местоположение файла php.exe

Не знаю как будет у Вас, но у меня половина css файлов имела формат cs, а png — pn, из-за этого в корне phpDocumentor создаём файл rename.bat, в который вписываем:
@Echo Off
for /f "tokens=1,2" %%a in ('dir /s /b *.cs') do ren %%a %%~nxas
for /f "tokens=1,2" %%a in ('dir /s /b *.pn') do ren %%a %%~nxag
for /f "tokens=1,2" %%a in ('dir /s /b *.tp') do ren %%a %%~nxal
@pause

Идём в папку user, в которой создаём файл myconf.ini, в нём будет наша конфигурация к phpDocumentor:
[Parse Data]
title = Название документации
hidden = false
parseprivate = on
javadocdesc = on
defaultpackagename = Главная
target = Исходящая директория
directory = Входящая директория
output=HTML:frames:default,HTML:frames:l0l33t,HTML:frames:phpdoc.de,HTML:frames:phphtmllib,HTML:frames:earthli,HTML:frames:DOM/default,HTML:frames:DOM/l0l33t,HTML:frames:DOM/phpdoc.de,HTML:frames:DOM/phphtmllib,HTML:Smarty:PHP
sourcecode=on

Возвращаемся опять в корень и запускаем phpdoc.bat. После этого в исходящей директории вы увидите несколько вариантов документаций. Выбираем ту которая больше Вам по душе, и указываем только её в параметре output нашей конфигурации.

Оформить шаблон вы можете в папке phpDocumentor/Converters/Формат/Тип/templates/class.tpl, путь не точный, и зависит от выбранного формата и типа.
Если вы собираетесь использовать русский язык — читаем фикс

Спасибо за внимание:)