Стандарты комментирования исходного кода

#python #c #javascript #java #php

Когда сталкиваюсь с opensource-проектами, в исходниках часто вижу комментарии такого
типа:
/**
 * Set the default fetch mode for this statement
 * @param mixed $mode fetch mode
 * @return CDbCommand
 * @see http://www.php.net/manual/en/function.PDOStatement-setFetchMode.php
 * @since 1.1.7
 */
public function setFetchMode($mode)
{
    $params=func_get_args();
    $this->_fetchMode = $params;
    return $this;
}

Полный код библиотеки здесь.
Многие распространенные IDE этот формат комментирования понимают, и строят на его
основе автодополнение кода. Это очень удобно. Да и читабельность кода на высшем уровне.
Вот интересно, что за стандарт такой? Где с ним можно поподробнее познакомиться?
И, если существуют другие стандарты для различных языков, про них тоже было бы интересно
узнать.    

Ответы

Ответ 1

Причем тут вообще Doxygen? Это называется Docstring. В данном примере же приведен
PHPDoc. Почитать документацию можно тут. IDE понимают только ограниченный набор тегов.
Это, как-правило, теги: 

@deprecated - помечает класс/метод, как устаревший. В IDE такие методы отображаются
перечеркнутые.
@method - какой-либо метод. Соответственно в IDE будет работать автодополнение по
этому методу, даже если его не существует. Так же если в качестве возвращаемого типа
указан класс, то будет работать автодополнение при цепочке вызовов.
@param - параметр метода/функции. Если в качестве типа параметра указан какой-либо
класс, то в методе будет работать автодополнение для этого класса.
@property, @property-read, @property-write - тоже самое, что и @method, только для
свойства.
@return - возвращаемый тип. IDE используют для автодополнения при цепочке вызовов.


Ответ 2

Этот стандарт комментирования в Java называется JavaDoc. 
Напомню - для тех кто не в курсях, Java первый массовый язык программирования, в
котором стандарт документирования кода является частью среды разработки.


Ответ 3

doxygen — система документирования для C++, C, Java, Objective-C, Python, IDL, Fortran,
VHDL, PHP, C#, и, в некоторой степени, D.

Плюсы Doxygen:


наличие утилит, обрабатывающих исходный код, извлекающих комментарии такого вида
и формирующих документацию разработчика;
формализация комментария — знакомому с разметкой Doxygen очень легко читать комментарии
(ясно, где описание функции, где описание параметров, где описание возвращаемого значения
и т.п. в отличие от свободного стиля оформления комментария).


Doxygen используется в весьма серьезных проектах:


пример использование разметки кода класса QFile из Qt Core (см. определение класса
с строки 187);
пример сгенерированной документации по API для D-BUS.


Ответ 4

Когда-то javadoc придумала компания Sun для Java.
http://java.sun.com/j2se/javadoc/faq/index.html#howdoiwritecomments
Позже, многие начали приходить к подобным комментариям в других языках. Doxygen использует
похожую концепцию