it-blog.club
Как сделать документацию кода PHP

Как сделать документацию кода PHP

Если вам часто приходится разбираться в чужом коде (ну или в своём старом, что не имеет ни какой разницы), то наверняка вы тратили ОЧЕНЬ много времени на то, чтобы понять что куда и зачем. Что самое интересное каждый из нас знает, что код необходимо комментировать, но речь сейчас пойдёт немного не об этом. Конечно я в этой статье затрону тему с комментариями, но всё же... Сейчас я бы вам хотел рассказать о том, как можно создать свою документацию, к своему PHP коду заюзав библиотеку phpDocumetor.

С самого начала давайте разберём, как работает данная библиотека.
Для того чтобы нам составить грамотную документацию, нам необходимо определённым образом прокомментировать наши классы и методы в коде.


/**
* Тестовый класс для примера
*
*/
class ClassName{

/**
* Простая функция для примера, которая возвращает свои параметры обратно
*
* @param $params array передаваемый при вызове
* @return $result array передаваемый в параметрах
*/
public function functionName($params)
{
$result = $params;
return $result;
}
}

Теперь продолжим установкой. Для того чтобы поставить нашу чудо библиотеку, вам потребуется наличие установленного PEAR на вашем сервере. Если же он отсутствует, то как его установить можете прочитать вот тут!

При наличии PEAR на вашем сервере, вам необходимо выполнить команду в консоли:

pear channel-discover pear.phpdoc.org

и потом

pear install phpdoc/phpDocumentor

Тут уже как повезёт, либо всё пройдет хорошо, либо у вас в консоли появится ошибка.

Если всё же второе, то следующие шаги вам должны помочь.

Введите в консоль поочерёдно 3 команды

pear upgrade pear

pear upgrade Console_Getopt

pear upgrade Structures_Graph

Ну и последнюю, собственно сама установка

pear install PhpDocumentor

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

phpdoc -o HTML:frames:earthli -d путь_до_проекта -t пусть_до_места_куда_созранить_доку

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

phpdoc -o HTML:frames:earthli -d /data/myWebSite/somothingFolder -t /data/myWebSite

И так, документация соберётся только из методов которые находится в файлах лежащих в папке somothingFolder. А сохранится как вы, наверное, уже поняли в корне сайта.
Используя параметр -o HTML:frames:earthli мы сообщаем что документация должна быть в формате html и в шаблоне earthli. Существует 2 разных шаблона для html, а так же 4 разных формата: html, pdf, xml, chm

Так же хотелось бы выделить огромный плюс phpDocumentor'a. А именно, то, что в случае ошибки он выдаёт об этом сообщение в консоли, и не просто сообщение, а именно ссылается на нужный файл и даже строку.

Но есть и минус, для кого-то он покажется достаточно устрашающим, но я сейчас сразу расскажу как быть. Минус заключается в том, что по умолчанию не поддерживается вывод в документацию русских символов. За место них вы просто увидите сбитую кодировку. А чтобы это исправить выполните описанное ниже.

Исправляем кодировку в phpDocumentor

Первое что нужно сделать это найти файл Setup.inc.php который находится в директории самого phpDoc на сервере.
В моём случае пусть будет вот таким: /usr/share/pear/PhpDocumentor/phpDocumentor

Находим там строку
if (stristr($ret, "utf-8") !== "")
И меняем на
if (stristr($ret, "utf-8") === false)

Второе это вам необходимо исправить кодировки в файлах отвечающих за структуру будущей документации. Я вам сейчас пока на примере html, остальные форматы делаются по аналогии. И так, для начала вам необходимо найти папку pear-data на вашем сервере. У меня они находится в /usr/share/ рядом с папкой pear. Заходим в неё, потом в PhpDocumentor ещё раз в phpDocumentor и в самом конце в папку Converters. Открываем папку html -> frames, далее папку с шаблонами и видим все доступные шаблоны. И так. Теперь вам необходимо в каждом файле нужного шаблона заменить кодировку с iso на utf-8. Сейчас на 100% не могу сказать где именно менять но точно это файлы: index и header. По моему только они есть. Кстати в этих файлах кодировка заменяется аж в 2 местах будьте внимательней.

После таких манипуляций у вас всё должно заработать.


it-blog.club 553
Автор: Ярослав Хмель


Если Вам понравилась статья, то можете поддержать блог переведя N сумму на кофе авторам или оплату хостинга!
В любом случае спасибо! А так же не забывайте про группу в ВК
ПОИСК ПО САЙТУ
Поддержать