Когда пишу код на 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)
{
…
} В коде наводим курсор на метод и видим его описание во всплывающей подсказке:
Изучая PHP, я задался вопросом «как это делается в PHP», чтобы следовать правилам хорошего тона и помочь себе в будущем, когда я буду читать свой собственный код. Немного поискав информацию, я нашёл как это делается и оставлю для себя заметку на будущее. Может она и другим поможет.
Для добавления описания к функции надо добавить комментарий перед функцией.
Важно. В комментарии в начале должны быть две звёздочки
/**
* Функция вычитания дробей
*
* @param string $fraction1 первая дробь
* @param string $fraction2 вторая дробь
* @return string возвращает разницу дробей в виде результирующей дроби
*
* Дополнительная информация отсутствует.
*/
function sub(string $fraction1, string $fraction2): string
{
...
} В примере имеется общее описание функции, описание переменных с указанием типов, описание возвращаемого функцией значения и дополнительная информация.
В коде при наведении курсора на имя вызываемой функции мы увидим всплывающую подсказку с информацией о функции:
Прошу обратить внимание, что я использую Visual Studio Code, а также дополнение «PHP Intelephense», чтобы редактор подсказывал пользовательские функции из других частей проекта (+ автодополнение, анализ кода, перехода к месту, где создана функция/класс/переменная). Чтобы подсказки не дублировались я отключил встроенную в редактор поддержку кода для PHP — «PHP Language Features».
