Автодокументация PHP в NetBeans 7.01 с использованием phpDocumentor, рассказываем, настраиваем, исправляем

    В этой статье вы получите новые и старые знания, в частности некоторые из них появились совершенно недавно в рунете, а некоторые вообще введены мной прямо на месте не отходя от кассы.

    Итак вы узнаете:
    • Базовую информацию о том, что такое автодокументация и как она делается в PHP
    • Настройка генератора документации phpDocumentor в NetBeans 7.01
    • Ссылка на исправленную мной библиотеку phpDocumentor со списком внесенных изменений, думаю некоторым может сразу же понадобиться
    • Ссылки на почитать

    На проекте столкнулся с тем, что потребовалось создать нормальную документацию. Писать отдельно документацию не самый лучший способ, базовое описание библиотеки можно выполнить и в стиле автодокументации. Начал разбираться в вопросе и о чудо, в NetBeans 7.01 оказывается поддерживается PHPDoc, вполне достойно и удобно. Был удивлен бедностью информации по этой тематике в русском сегменте сети. Кроме того, я нашел несколько подводных камней, которые создавали проблемы при настройке под Windows.

    Если заинтересовались, то добро пожаловать под кат



    Некоторые не знают, что такое автодокументаия. Многие ей не пользуются из-за размеров комментируя код по старинке в одну или две строчки, либо вообще не комментируют. Этим много кто грешит и я, иногда =). Например, среди другого скудного описания, мой любимый комментарий в заглавии 800-ста строчного файла:
    // От себя добавлю: не знаю сколько я выпил энергетиков, что все это смог написать.
    

    Что такое автодокументация в PHP


    Автодокументация — это мануал по автомобилю такая штука, которая позволяет писать комментарии к коду. При этом внутри IDE будет отображаться подсказки по коду, методе, функции, файлу и др. Далее, на основе нее возможно генерировать полноценную документацию по всему коду в каком-либо формате HTML, PDF, XML etc. Например, в MSDN — все, что вы видите в таблице создано с помощью автодокументации руками программистов. За всем остальным следит отдел документации, которые пишут дополнительное разжевывание и примеры.

    Применительно к генерации документации для PHP, существуют разные библиотеки. Самые интересные которые я нашел:

    Я принял решение использовать 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-ти бального барьера.
    Поделиться публикацией
    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама

    Комментарии 23

      0
      Почти оффтоп:
      Будте добры, расшифруйте картинку, а то шрифт нечитаем.
        +3
        Комментируй код и пили
        open source *****Ъ
          0
          Спасибо!
            0
            В общем неудачный юмор. Поначалу вроде смешно, а потом как-то не то. Я уже картинку не стал переделывать, мужика взял из первой версии логотипа поста. Эта версия мне показалась более понятной, так как она объясняет технологии которые будут в посте описываться.
          0
          Вообще, конечно, поразительно, что шаблоны всё еще в iso-8859-1 вместо utf-8… судя по трекеру, просьбы запилить utf-8 начинаются с 2004 года.
            0
            Поразительно, что программисты до сих пор пишут комментарии на русском.
              0
              Зачем дважды насиловать свой мозг и ГуглТранслейт? :)
                +1
                Этот Ваш комментарий тоже написан на русском;
              0
              В названии статьи опечатка: Netbeanes вместо Netbeans.
                +1
                Боже мой, кто-то еще пользуется эти трупом? (PhpDocumentor) он же не развивается миллион лет, и адекватных форков нет
                  +1
                  А чем лучше пользоваться?
                    +2
                    Я пробовал 2: PHPDoctor (например Doctrine 2 им пользуются) и DocBlox (используется ZF и еще многими, на сайте есть список)
                      +1
                      Я посмотрел, но что-то у меня не сразу же получилось запустить и мануалов нет, кроме как через командую строку. С виду красивее получается, спасибо за инфу, добавил в статью.
                    0
                    чем вы пользуетесь?
                      0
                      Ну, я не знаю. Куда ссылка из NetBeans открылась, тем я и начал пользоваться. С виду вроде очень даже прилично отображает документацию, не знаю чем он там труп.

                      Попробую ваши, напишу мнение.
                        0
                        Сейчас глянул, оказывается они ожили и даже 2 версии выпустили за последние 3 месяца (спустя 3 года). Раньше там даже неймспейсы не поддерживались (что логично, какие неймспейсы в 2008 году =) ). Не могу найти список изменений по 2 последним версиям. Есть у кого ссылка? Но сильно сомневаюсь, что они уже догнали современные аналоги.
                      –2
                      Трэш
                        –1
                        Скорее всего карму минусуют потому что статья уровня начинающих программистов, которые только только начинають знакомиться с документированием кода. Под документированием я не имею ввиду написание какой то херьни про кофе/пиво/энергетик в начале толстого файла. По этому многие мало мальски опытные программисты не видять в статье пользы, по этому они просят тебя больше не писать таких статей минусуя твою карму.
                          0
                          Грамматику поправьте, будьте любезны
                          «оказывается поддерживаться PHPDoc» — «поддерживается»

                          Автор, пиши ещё :)
                            0
                            Исправил, как только будет что-либо достойное, обязательно напишу. Например в планах висит поправить библиотеку xdebug, но пока как-то не до нее.
                              0
                              А с xdebug-ом то что? Поломался?

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

                        Самое читаемое