Написание документации к коду — задача не самая приятная и радостная, но если вы делаете большой проект и/или участвуете в командной разработке, то, я бы сказал, это вещь просто даже необходимая. Если у вас много разных интерфейсов, классов, функций, методов, с различными парметрами и выходными данными, и с этим приходится работать более чем одному разработчику, очень здорово иметь под рукой описание всех этих самых классов, их атрибутов и параметров, а не бегать каждый раз к разработчику и спрашивать какой параметр что значит. Это ни в коем случае не отменяет того, что сами названия классов, методов и параметров должны иметь осмысленные имена, но не об этом сейчас речь. Сейчас мы поговорим о документировании исходных кодов на 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.
/* Там слева вверху был логотип 🙂 */
