Какие причины и обстоятельства следует предпочесть javadoc / phpdoc обычным комментариям?

Вся причина, по которой люди используют Javadoc, - это согласованность и удобочитаемость - если вы знаете синтаксис, он позволяет легко взглянуть на чужой код (или наоборот) и понять смысл сразу. Вместо того, чтобы иметь что-то вроде:

// This method is used for counting sheep just before bed time
// It's really awesome, and takes the bed-time, and also age,
// And also number of sheep, in reverse order.

Что требует времени для обработки; гораздо приятнее увидеть:

/**
 * Count the number of sheep at bedtime
 *
 * @author Tom Walters 
 *
 * @param sheep   The number of sheep to count
 * @param age     The age of the person going to bed
 * @param bedTime The time of going to bed in 24hr format
 * @return The sheep were counted successfully
 */

Сразу видно, сколько здесь параметров и для чего каждый из них. То же самое и с возвращаемым типом. Также очень полезно при работе в команде, чтобы автор был там, тогда вы знали, на кого кричать, когда овца сбивается с пути.

Что касается /** - он помогает отличить этот стиль от таких вещей, как случайные комментарии и онлайн-комментарии, и является хорошим соглашением, помогающим Javadoc выделяться при просмотре кода.

Как правило, вы будете поддерживать код больше, чем писать его, поэтому наличие четко определенного синтаксиса, подобного этому, - отличная идея - это приведет к тому, что вы будете уделять больше времени размышлениям о решении проблем, а не расшифровка больших блоков текста для получения основной информации.

Форма /** */ обычно используется для документации. Поэтому, если вы хотите задокументировать класс, файл, функцию, метод класса, поле класса или переменную, вы должны использовать эту форму.

Форма /* */ содержит только комментарии к коду, как и //.

Некоторые IDE будут использовать информацию phpDoc, содержащуюся в /** */ блоках, чтобы показать вам некоторую подсказку. Кроме того, такие программы, как phpDocumentor, используют /** */ блоки для создания файлов документации.

Просматривая все комментарии и обсуждения выше, похоже, у вас все еще есть вопросы об использовании комментариев Javadoc только к функциям. Ответ будет ДА, вы можете использовать комментарии javadoc к функциям, которые не обязательно должны быть в определении класса.

Зачем использовать комментарии javadoc вместо обычных? Основная причина заключается в использовании инструмента Javadoc, который создаст справочный документ локального API (html), в котором объясняется, как использовать ваши функции и какие типы возврата ожидать от этих функций (и методов класса). Без комментариев javadoc инструменту Javadoc нечего было бы помещать в сгенерированный документ API. В комментариях javadoc вы помещаете то, что будет отформатировано в файлы html для вашего собственного API. Инструмент javadoc видит / ** как специальный комментарий и читает это содержимое. Компилятор Java (или интерпретатор PHP) увидит / ** и подумает, что это / * игнорирует все до следующего * /, они рассматривают это как любой обычный комментарий.

Поэтому, если вы планируете иметь легкий для чтения ссылочный справочный документ с возможностью нажатия, комментарии javadoc абсолютно необходимы, в противном случае они не имеют значения. Однако использование Javadoc API в качестве справочника позволяет значительно сэкономить время, чтобы посмотреть, как работают ваши функции, без необходимости искать их в коде.

Иметь Javadoc API моих файлов - это здорово, если мне нужен кто-то еще, чтобы помочь в проекте. Гораздо проще щелкнуть гиперссылку в веб-браузере, чтобы увидеть объяснение функции, вместо того, чтобы искать файл, открывать файл, искать функцию, читать код и определять, что она делает.

Воспользуемся этим примером:

public int addSquares( int x, int y ) {
  int value = x*x + y*y;
  return value;
}

Само по себе вы должны прочитать, что эта функция принимает два целых числа, возводит их в квадрат и возвращает сумму обоих квадратов. если бы мы были в Javadoc, функция с:

/**
* Squares two numbers, and returns the sum of those squared numbers.
* @param x first value to square
* @param y second value to square
* @return value of x*x + y*y
*/

если вы запустили свой файл .java с помощью инструмента Javadoc, у вас будет файл html, который показывает:

int addSquares( int x, int y )
    Squares two numbers, and returns the sum of those squared numbers.

Это дает вам тип возвращаемого значения, параметры и краткое описание функции. Также addSquares будет гиперссылкой на более описательный раздел на той же HTML-странице, который будет выглядеть примерно так:

addSquares
public int addSquares (int x, int y)
Возводит два числа в квадрат и возвращает сумму этих квадратов чисел.

Параметры:
первое значение x преобразуется в квадрат
второе значение y преобразуется в квадрат

Возвращает:
значение x * x + y * y

Да, в этом примере очень просто читать код, но когда ваши функции / методы / классы становятся более сложными, гораздо быстрее использовать задокументированный справочный API, созданный с помощью комментариев Javadoc. Поэтому, если вы не планируете создавать справочную документацию по API, комментарии javadoc ничем не отличаются от обычных комментариев, за исключением того, что они имеют другой цвет в вашем редакторе.