В этой статье вы получите новые и старые знания, в частности некоторые из них появились совершенно недавно в рунете, а некоторые вообще введены мной прямо на месте не отходя от кассы.
Итак вы узнаете:
На проекте столкнулся с тем, что потребовалось создать нормальную документацию. Писать отдельно документацию не самый лучший способ, базовое описание библиотеки можно выполнить и в стиле автодокументации. Начал разбираться в вопросе и о чудо, в NetBeans 7.01 оказывается поддерживается PHPDoc, вполне достойно и удобно. Был удивлен бедностью информации по этой тематике в русском сегменте сети. Кроме того, я нашел несколько подводных камней, которые создавали проблемы при настройке под Windows.
Если заинтересовались, то добро пожаловать под кат
Некоторые не знают, что такое автодокументаия. Многие ей не пользуются из-за размеров комментируя код по старинке в одну или две строчки, либо вообще не комментируют. Этим много кто грешит и я, иногда =). Например, среди другого скудного описания, мой любимый комментарий в заглавии 800-ста строчного файла:
Автодокументация — этомануал по автомобилю такая штука, которая позволяет писать комментарии к коду. При этом внутри IDE будет отображаться подсказки по коду, методе, функции, файлу и др. Далее, на основе нее возможно генерировать полноценную документацию по всему коду в каком-либо формате HTML, PDF, XML etc. Например, в MSDN — все, что вы видите в таблице создано с помощью автодокументации руками программистов. За всем остальным следит отдел документации, которые пишут дополнительное разжевывание и примеры.
Применительно к генерации документации для PHP, существуют разные библиотеки. Самые интересные которые я нашел:
Я принял решение использовать PHPDocumentor. Работа данной библиотеки меня полностью удовлетворяет, особенно после моих правок в ней.
— Код
— Подсказки IDE: мы узнаем, что функция не очевидно возвращает string
— Автодокументация:
Я работаю под Windows. У меня xampp — это очень удобная вещь для тех кто не знал, но в ней нет предварительно настроенного PHPDocumentor. К примеру, предварительно настроенный PHPUnit есть. Не будем винить создателей xampp, а перейдем к ручной настройке. Что бы там где не писали, про умные команды вроде PEAR, лучше сделать как у меня. От себя добавлю, что я сам люблю описывать так, что бы это 100% работало по описанию со всеми абсолютными путями, так что можете быть уверены, что оно заработает, если сделать как тут:
— Начальная настройка
XAMPP у меня сконфигурирован в директории D:\xampp
Если что было в D:\xampp\php\PEAR\PhpDocumentor не боимся и удаляем. Там нет никаких умных конфигураций от xampp.
— Загрузка кода
Не думаем о PEAR командах, качаем PHPDocumentor прямо с сайта разработчика (ссылки внизу + там моя поправленная версия)
Распаковываем все в директорию PEAR. Вам потребуется выполнить некоторые магические операции над директориями: удаление ненужной иерархии, переименования и т.п. В результате файлы и иерархия, в частности файл phpdoc.bat должен оказался в этой директории: D:\xampp\php\PEAR\PhpDocumentor
— Настройка библиотеки
Теперь требуется настроить саму библиотеку. Для этого идем в файл phpdoc.bat
В нем мы будем указывать путь к нашему установленному PHP интерпретатору, а так же делать переключение рабочий директории.
Вместо:
SET phpCli=C:\usr\local\php\cli\php.exe
Вставляем:
SET phpCli=D:\work\rumb-software\xampp\php\php.exe
CD /D D:\xampp\php\PEAR\PhpDocumentor
Внимание, подводный камень!
Если вы будете размещать XAMPP на ином диске от C:, то при выборе директории (команда CD) требуется дописывать аргумент /D — на это ушло пол часика, думая «че оно скрипт не видит?», пока не пошел на кухню наливать чай, случайно вспомнив об этой Microsoft-magic.
— Настройка IDE
Теперь сконфигурируем IDE для работы с этим расширением.
Для этого идем в
NetBeans 7.01 > Options > PHP > PHPDoc > PhpDoc script
Вставляем вот эту строку:
D:/xampp/php/PEAR/PhpDocumentor/phpdoc.bat -o HTML:frames:earthli
Эта строчка укажет IDE исполняемый скрипт и передаст дополнительные переменные, так к слову говорят туда можно что-то другое написать в качестве параметров. Например, можно поучить в результате PDF. Не проверял, да мне и не нужно.
Внимание подводный камень!
Слешь должен быть прямой "/". Если вы будете выбирать через Browse — то NetBeans подставит обратный слешь.
— Теперь настроим путь, куда будет сохраняться документация
Создаем проект типа PHP, ну это я не буду тут описывать. Скажем, я его назвал example-project и поместил в D:/xampp/htdocs/example-project, версия PHP 5.3 кодировка UTF-8
Правой кнопкой по проекту
example-project > properties > PhpDoc > Target Directory
Вставляем строчку (Тоже есть проблема со слешами!):
D:/xampp/htdocs/phpdoc
— Запуск
После этих действий, генерация доступна по правой кнопке мыши по проекту > Generate PhpDoc.
Еще в Include Path можно подключить директорию полученной документации, что бы файлы были видны через IDE. В реальности это вообще это не нужно, но радость =)
В процессе генерации я встретил несколько проблем.
— Выскакивают нотисы
У меня по умолчанию на девелоперском PHP максимальный уровень ошибок, варнигнов, нотисов и стриктов. Во время генерации документации в файлы начали валиться все эти ошибки, в основном создавал их класс Smarty, выражаю уважение к разработчикам PHPDocumentor — у них все хорошо. Я исправил эту проблему принудительно запретив это делать в библиотеке.
Добавил error_reporting(E_ERROR); в файле
D:\xampp\php\PEAR\PhpDocumentor\phpDocumentor\phpdoc.inc
— Проблема с кодировкой
Я немного русский и мне свойственно писать русские комментарии. Возникли проблемы кодировки. Вот у меня например UTF-8, а в библиотеке в шаблоны генерации была вшита другая кодировка iso-8859-1. В результате получалась чушь. Благо зная как работает Smarty, исправил 3-4 файла с кодом и прописал в шаблоны динамическую переменную. Теперь кодировку выходных шаблонов можно менять вручную в файле D:\xampp\php\PEAR\PhpDocumentor\phpDocumentor\phpdoc.inc с помощью константы CHARSET, если надо то переменную {$charset} можно добавлять к любому шаблону из всего набора, я посмотрел charset заголовки есть не во всех шаблонах.
— Помощь общественности
От себя добавлю, что я считаю себя неправым, что не разместил доступ к этим фиксам через командную строку, но поймите меня правильно у меня тоже время не резиновое, я отправил создателям предложение внести мои правки в следующую ревизию и им это будет проще, так как они архитекторы всей библиотеки.
PHPDocumentor ссылка на библиотеку:
http://sourceforge.net/projects/phpdocu/files/
Исправленный PHPDocumentor: если не загружается, обращайтесь в личку. Возможно я опять положил свой бедный сервак.
http://yadi.sk/d/7WnrUy5z0qE7n
Ссылка на документацию по PhpDoc формату:
http://manual.phpdoc.org/HTMLframesConverter/default/
Заморское видео — инструкция по настройке:
http://netbeans.org/kb/docs/php/screencast-phpdoc.html
Проблема со слешами и какая ошибка будет в этом случае, описана тут:
pachkov.ru/?p=1222
Текст для индексации поисковиком:
Ошибка в NetBeans при создании PhpDoc (for Windows)
Ошибка при вызове фильтра. Было создано следующее сообщение об ошибке:
java.util.regex.PatternSyntaxException: Illegal hexadecimal escape sequence near index 10
(.*)(C:\xampp\htdocs\PhpProject1\phpdoc/errors\.html)(.*)
Спасибо за внимание!
UPD: исправил кучу тупых сонных опечаток
UPD2: не понимаю, кто сливает карму вроде рерайтов не пишу, и статья сугубо техническая и не холиварная. Надо вообще убрать анонимность изменения кармы, что бы можно было выставлять на суд общественности. Поражен и обижен, но признаюсь что минусовать стали меньше, после введения 15-ти бального барьера.
Итак вы узнаете:
- Базовую информацию о том, что такое автодокументация и как она делается в PHP
- Настройка генератора документации phpDocumentor в NetBeans 7.01
- Ссылка на исправленную мной библиотеку phpDocumentor со списком внесенных изменений, думаю некоторым может сразу же понадобиться
- Ссылки на почитать
На проекте столкнулся с тем, что потребовалось создать нормальную документацию. Писать отдельно документацию не самый лучший способ, базовое описание библиотеки можно выполнить и в стиле автодокументации. Начал разбираться в вопросе и о чудо, в NetBeans 7.01 оказывается поддерживается PHPDoc, вполне достойно и удобно. Был удивлен бедностью информации по этой тематике в русском сегменте сети. Кроме того, я нашел несколько подводных камней, которые создавали проблемы при настройке под Windows.Если заинтересовались, то добро пожаловать под кат
Некоторые не знают, что такое автодокументаия. Многие ей не пользуются из-за размеров комментируя код по старинке в одну или две строчки, либо вообще не комментируют. Этим много кто грешит и я, иногда =). Например, среди другого скудного описания, мой любимый комментарий в заглавии 800-ста строчного файла:
// От себя добавлю: не знаю сколько я выпил энергетиков, что все это смог написать.
Что такое автодокументация в PHP
Автодокументация — это
Применительно к генерации документации для PHP, существуют разные библиотеки. Самые интересные которые я нашел:
- doxygen
- PHPDocumentor
- docblox — UPD
- phpdoctor — UPD
Я принял решение использовать PHPDocumentor. Работа данной библиотеки меня полностью удовлетворяет, особенно после моих правок в ней.
Примеры
— Код
/**
* Складывает два числа и возвращает строковое значение
*
* @param int $arVarOne
* @param int $arVarTwo
* @return string
*/
function sum_return_string($arVarOne, $arVarTwo)
{
$result = $arVarOne + $arVarTwo;
return "$result"; // преобразование типа!!!
}
— Подсказки IDE: мы узнаем, что функция не очевидно возвращает string
— Автодокументация:
Настройка скрипта автодокументации PHPDocumentor
Я работаю под Windows. У меня xampp — это очень удобная вещь для тех кто не знал, но в ней нет предварительно настроенного PHPDocumentor. К примеру, предварительно настроенный PHPUnit есть. Не будем винить создателей xampp, а перейдем к ручной настройке. Что бы там где не писали, про умные команды вроде PEAR, лучше сделать как у меня. От себя добавлю, что я сам люблю описывать так, что бы это 100% работало по описанию со всеми абсолютными путями, так что можете быть уверены, что оно заработает, если сделать как тут:
— Начальная настройка
XAMPP у меня сконфигурирован в директории D:\xampp
Если что было в D:\xampp\php\PEAR\PhpDocumentor не боимся и удаляем. Там нет никаких умных конфигураций от xampp.
— Загрузка кода
Не думаем о PEAR командах, качаем PHPDocumentor прямо с сайта разработчика (ссылки внизу + там моя поправленная версия)
Распаковываем все в директорию PEAR. Вам потребуется выполнить некоторые магические операции над директориями: удаление ненужной иерархии, переименования и т.п. В результате файлы и иерархия, в частности файл phpdoc.bat должен оказался в этой директории: D:\xampp\php\PEAR\PhpDocumentor
— Настройка библиотеки
Теперь требуется настроить саму библиотеку. Для этого идем в файл phpdoc.bat
В нем мы будем указывать путь к нашему установленному PHP интерпретатору, а так же делать переключение рабочий директории.
Вместо:
SET phpCli=C:\usr\local\php\cli\php.exe
Вставляем:
SET phpCli=D:\work\rumb-software\xampp\php\php.exe
CD /D D:\xampp\php\PEAR\PhpDocumentor
Внимание, подводный камень!
Если вы будете размещать XAMPP на ином диске от C:, то при выборе директории (команда CD) требуется дописывать аргумент /D — на это ушло пол часика, думая «че оно скрипт не видит?», пока не пошел на кухню наливать чай, случайно вспомнив об этой Microsoft-magic.
— Настройка IDE
Теперь сконфигурируем IDE для работы с этим расширением.
Для этого идем в
NetBeans 7.01 > Options > PHP > PHPDoc > PhpDoc script
Вставляем вот эту строку:
D:/xampp/php/PEAR/PhpDocumentor/phpdoc.bat -o HTML:frames:earthli
Эта строчка укажет IDE исполняемый скрипт и передаст дополнительные переменные, так к слову говорят туда можно что-то другое написать в качестве параметров. Например, можно поучить в результате PDF. Не проверял, да мне и не нужно.
Внимание подводный камень!
Слешь должен быть прямой "/". Если вы будете выбирать через Browse — то NetBeans подставит обратный слешь.
— Теперь настроим путь, куда будет сохраняться документация
Создаем проект типа PHP, ну это я не буду тут описывать. Скажем, я его назвал example-project и поместил в D:/xampp/htdocs/example-project, версия PHP 5.3 кодировка UTF-8
Правой кнопкой по проекту
example-project > properties > PhpDoc > Target Directory
Вставляем строчку (Тоже есть проблема со слешами!):
D:/xampp/htdocs/phpdoc
— Запуск
После этих действий, генерация доступна по правой кнопке мыши по проекту > Generate PhpDoc.
Еще в Include Path можно подключить директорию полученной документации, что бы файлы были видны через IDE. В реальности это вообще это не нужно, но радость =)
Несколько проблем в библиотеке исправленные мной
В процессе генерации я встретил несколько проблем.
— Выскакивают нотисы
У меня по умолчанию на девелоперском PHP максимальный уровень ошибок, варнигнов, нотисов и стриктов. Во время генерации документации в файлы начали валиться все эти ошибки, в основном создавал их класс Smarty, выражаю уважение к разработчикам PHPDocumentor — у них все хорошо. Я исправил эту проблему принудительно запретив это делать в библиотеке.
Добавил error_reporting(E_ERROR); в файле
D:\xampp\php\PEAR\PhpDocumentor\phpDocumentor\phpdoc.inc
— Проблема с кодировкой
Я немного русский и мне свойственно писать русские комментарии. Возникли проблемы кодировки. Вот у меня например UTF-8, а в библиотеке в шаблоны генерации была вшита другая кодировка iso-8859-1. В результате получалась чушь. Благо зная как работает Smarty, исправил 3-4 файла с кодом и прописал в шаблоны динамическую переменную. Теперь кодировку выходных шаблонов можно менять вручную в файле D:\xampp\php\PEAR\PhpDocumentor\phpDocumentor\phpdoc.inc с помощью константы CHARSET, если надо то переменную {$charset} можно добавлять к любому шаблону из всего набора, я посмотрел charset заголовки есть не во всех шаблонах.
— Помощь общественности
От себя добавлю, что я считаю себя неправым, что не разместил доступ к этим фиксам через командную строку, но поймите меня правильно у меня тоже время не резиновое, я отправил создателям предложение внести мои правки в следующую ревизию и им это будет проще, так как они архитекторы всей библиотеки.
Ссылки на материалы
PHPDocumentor ссылка на библиотеку:
http://sourceforge.net/projects/phpdocu/files/
Исправленный PHPDocumentor: если не загружается, обращайтесь в личку. Возможно я опять положил свой бедный сервак.
http://yadi.sk/d/7WnrUy5z0qE7n
Ссылка на документацию по PhpDoc формату:
http://manual.phpdoc.org/HTMLframesConverter/default/
Заморское видео — инструкция по настройке:
http://netbeans.org/kb/docs/php/screencast-phpdoc.html
Проблема со слешами и какая ошибка будет в этом случае, описана тут:
pachkov.ru/?p=1222
Текст для индексации поисковиком:
Ошибка в NetBeans при создании PhpDoc (for Windows)
Ошибка при вызове фильтра. Было создано следующее сообщение об ошибке:
java.util.regex.PatternSyntaxException: Illegal hexadecimal escape sequence near index 10
(.*)(C:\xampp\htdocs\PhpProject1\phpdoc/errors\.html)(.*)
Спасибо за внимание!
UPD: исправил кучу тупых сонных опечаток
UPD2: не понимаю, кто сливает карму вроде рерайтов не пишу, и статья сугубо техническая и не холиварная. Надо вообще убрать анонимность изменения кармы, что бы можно было выставлять на суд общественности. Поражен и обижен, но признаюсь что минусовать стали меньше, после введения 15-ти бального барьера.
