Когда пишу код на C#, то всегда добавляю к методам и классам описание, чтобы в любом месте кода можно было прочитать их описание. Сейчас изучаю PHP и также решил всё делать по уму.

Как это делается в C#? Вот так добавляем описание к методу в C#:

/// <summary> Метод отображения/скрытия строк с неактивными офисами </summary>
/// <param name="name"> Название офиса </param>
/// <param name="address"> Адрес офиса </param>
/// <param name="active"> Активный или нет </param>
public void ShowHideNoActiveOffice(string name, string address, bool active)
{
…
}

В коде наводим курсор на метод и видим его описание во всплывающей подсказке:

Метод с кодом C#

Изучая PHP, я задался вопросом «как это делается в PHP», чтобы следовать правилам хорошего тона и помочь себе в будущем, когда я буду читать свой собственный код. Немного поискав информацию, я нашёл как это делается и оставлю для себя заметку на будущее. Может она и другим поможет.

Для добавления описания к функции надо добавить комментарий перед функцией.

Важно. В комментарии в начале должны быть две звёздочки

/**
 * Функция вычитания дробей
 * 
 * @param string $fraction1 первая дробь
 * @param string $fraction2 вторая дробь
 * @return string возвращает разницу дробей в виде результирующей дроби
 * 
 * Дополнительная информация отсутствует.
 */
function sub(string $fraction1, string $fraction2): string
{
...
}

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

В коде при наведении курсора на имя вызываемой функции мы увидим всплывающую подсказку с информацией о функции:

Пример отображения подсказок PHP

Прошу обратить внимание, что я использую Visual Studio Code, а также дополнение «PHP Intelephense», чтобы редактор подсказывал пользовательские функции из других частей проекта (+ автодополнение, анализ кода, перехода к месту, где создана функция/класс/переменная). Чтобы подсказки не дублировались я отключил встроенную в редактор поддержку кода для PHP — «PHP Language Features».