Комментарии к сообщению данных документации PHP и возвращения JSON

Question

У меня есть два вопроса собственно:

1. Для некоторых функций я отправляю формы для них, я могу упомянуть их @params в комментариях или что:

   /* some descriptions 
   * 
   * @param string userName 
   */ 
   
   
   
   public function add(){ 
         $userName = $_POST['user'] 
        ...... 
   } 
   

2. с некоторой функцией я возвращающийся данными в формате JSON, как упомянуть JSON в качестве возвращаемого типа и формата:

   /* some descriptions 
       * 
       * @return JSON [{id, name,...}] 
       */ 
   

Answer 1

Вы можете написать все, что хотите, в комментариях. Тем не менее, это не обычное использование - @param и @return должны описывать фактические параметры и возвращаемые значения рассматриваемой функции. См. draft PHP-FIG recommendation для чего (в основном) обычный.

Если вы возвращающая строку JSON, было бы лучше, чтобы документировать его как

@return string Text here describing what is being returned

так, насколько PHP обеспокоен это просто еще одна строка.