Рубрики
Web-Разработка

Использование php-doc & doxygen для генерации php-документации

Написание документации к коду — задача не самая приятная и радостная, но если вы делаете большой проект и/или участвуете в командной разработке, то, я бы сказал, это вещь просто даже необходимая. Если у вас много разных интерфейсов, классов, функций, методов, с различными парметрами и выходными данными, и с этим приходится работать более чем одному разработчику, очень здорово иметь под рукой описание всех этих самых классов, их атрибутов и параметров, а не бегать каждый раз к разработчику и спрашивать какой параметр что значит. Это ни в коем случае не отменяет того, что сами названия классов, методов и параметров должны иметь осмысленные имена, но не об этом сейчас речь. Сейчас мы поговорим о документировании исходных кодов на php. Я для этих целей использую такой инструмент как Doxygen.

Что такое Doxygen?

Для тех, кто не в курсе что это такое, краткая справка. Как написано на сайте проекта:
Doxygen — это кроссплатформенная система документирования исходных текстов, которая поддерживает C/C++, Objective-C, Python, Java, IDL, PHP, C#, Fortran, VHDL и, частично, D.

Сайт проекта: http://www.stack.nl/~dimitri/doxygen/

Данная утилитка есть под все основные платформы: Windows/Linux/MacOS; а некоторые энтузиасты даже портировали ее под Solaris/OS/2/IRIX/FreeBSD. Так же на сайте имеется прекрасная документация как в pdf-формате, так и в chm-формате. Очень рекомендую с ней ознакомиться.

Документирование php-кода.

Не буду описывать процесс установки doxygen на комп, потому как это простая процедура, не отличающаяся от установки любого другого приложения.
Для комментирования кода можно использовать несколько стилей, среди которых есть Javadoc, C-style комментарии или же Qt-style комментарии. Я для себя выбрал формат Javadoc по той причине, что он, можно сказать, совместим с форматом phpdoc, и, следовательно, если вы пишите код не в блокноте, а в какой-нибудь среде разработки, которая автоматически понимает phpdoc комментарии, это дает вам сразу возможность видеть подсказки в коде, автоматически подсказывать типы и значения параметров функций и прочие радости жизни. Это проверено в Eclipse IDE (PDT) и Netbeans, но подозреваю, что и в других продвинутых средах разработки это тоже будет работать. Далее будут скриншоты того как это выглядит в Eclipse. А пока приведу пример документирования php-кода:

cr = curl_init();
          $this->url = $url;
          $this->data = $data;
          $this->err = false;
        
          curl_setopt($this->cr, CURLOPT_URL, $url);
          if($submit_type == "POST")
               curl_setopt($this->cr, CURLOPT_POST, 1 );
          if($data)
               curl_setopt($this->cr, CURLOPT_POSTFIELDS, $data);
        
          curl_setopt($this->cr, CURLOPT_RETURNTRANSFER, 1);        
        
     }
   
     /**
      * Выполнение запроса на сервере
      */
     function exec_query()
     {
          $this->result = curl_exec($this->cr);
        
          if (curl_errno($this->cr))
               $this->err = curl_error($this->cr);
          curl_close($this->cr);
     }
   
     /**
      * Получение результата запроса
      * @return Результат запроса
      */
     function get_answer()
     {
          return $this->result;
     }
   
     /**
      * Проверка на ошибку
      * @return false или описание ошибки
      */
     function check_error()
     {
          return $this->err;
     }
   
}

?>

Если описать класс таким образом, то, например, в Eclipse в любом месте проекта, где вы захотите получить подсказку по методам,свойствам класса, вы увидите примерно следующее:

По моему, это замечательно: сразу видно что делает этот метод, какие параметры он принимает на вход и какого они типа. Ко всему прочему во вьюхе «outline» все функции показываются с типами параметров, что тоже очень приятно.

Если у вас есть абстрактные классы, от которых наследуются реальные, то нет необходимости описывать каждый метод в каждом классе, достаточно описать метод в абстрактном классе, а в наследуемых сделать ссылки и все будет прекрасно работать, причем Эклипс практически сам генерит нужный комментарий, так что не переживайте, что вам придется их писать самим.

query = "CALL Process_User_Login ('".$login."', '".$password."', '".$session_id."', ".$module_id.", '".$client_ip."');";
          $this->make_query();
     }

     /**
       * Обработка выхода пользователя из системы
       * @see includes/classes/CDb_Abstract#get_query_Process_User_Logout($user_id)
       */
     public function get_query_Process_User_Logout($user_id)
     {
          $this->query = "CALL Process_User_Logout (" . $user_id . ");";
          $this->make_query();
     }
...
}

?>

Дополнительные плюшки.

Так же doxygen обладает еще рядом возможностей, среди которых есть генерация графа связи классов. Что в общем и целом очень полезная фича. Причем он показывает граф как «сверху-вниз», то есть для базового класса будут показаны все наследуемые, так и «снизу-вверх», то есть для класса будут показаны все предки. Выглядит это так:


Ну и напоследок, скрины того, как выглядит сгенерированная документация в формате html.
/* Там слева вверху был логотип 🙂 */