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

PHP
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 Название
Аналогично @package, но действует как подгруппа.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


1 комментарий

комментарий был удален
Только зарегистрированные и авторизованные пользователи могут оставлять комментарии.