Создание документации на основе 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, путь не точный, и зависит от выбранного формата и типа.
Если вы собираетесь использовать русский язык — читаем фикс
Спасибо за внимание:)