apidoc class @property

Обсуждение документации второй версии фреймворка. Переводы Cookbook и авторские рецепты.
Ответить
fly2k
Сообщения: 155
Зарегистрирован: 2013.03.19, 05:31

apidoc class @property

Сообщение fly2k »

Ку!

Не могу понять как правильно документировать магические свойства классов(тех которых нет в php объявлении класса, но на которые есть геттер и/или сеттер). Те свойства которые описаны перед классом по типу "@property type $name description" в доки не попадают :( Остается описывать сами геттер/сеттеры, но вот мне хочется чтобы в доках были нормальные описания магических свойств, а не их геттеров...

Особенно, в этом смысле интересуют маг.свойства которые обычно используются для отношений моделей. Например, у какой то модели(Model) есть ссылка на владельца(User). Типа:

Код: Выделить всё

    /**
     * @return \yii\db\ActiveQuery
     */
    public function getUser()
    {
        return $this->hasOne(User::className(), ['id' => 'user_id']);
    }
...и $model->getUser() вернёт ActiveQuery, но $model->user - уже экземпляр класса User(см. почему). То есть уже хотя бы по этому нада Model::$user отдельно описывать в доках.

Подскажите плз.

Спасибо!
// Yii2Rulez!
astronin
Сообщения: 606
Зарегистрирован: 2012.01.30, 17:46

Re: apidoc class @property

Сообщение astronin »

пишите в комментариях к классу, добавляя описание переменной
/**
*
* @property <your path>\User $user
*/
fly2k
Сообщения: 155
Зарегистрирован: 2013.03.19, 05:31

Re: apidoc class @property

Сообщение fly2k »

astronin писал(а):пишите в комментариях к классу, добавляя описание переменной
/**
*
* @property <your path>\User $user
*/
ну в этом и вопрос - такой камент _перед_ классом канает, например, для phpstorm'а (свойство "подсказывается"), но когда я генерю apidoc api ..., в реультирующем файле доки по классу этого свойства нет, только геттеры/сеттеры :(
// Yii2Rulez!
zelenin
Сообщения: 10596
Зарегистрирован: 2013.04.20, 11:30

Re: apidoc class @property

Сообщение zelenin »

fly2k писал(а):Те свойства которые описаны перед классом по типу "@property type $name description" в доки не попадают
astronin писал(а): пишите в комментариях к классу, добавляя описание переменной
/**
*
* @property <your path>\User $user
*/
fly2k
Сообщения: 155
Зарегистрирован: 2013.03.19, 05:31

Re: apidoc class @property

Сообщение fly2k »

ну и, в общем, даже для сгенеренной с помощью gii модельки(там есть phpdoc описания столбцов таблицы) - и они тоже в доки не попадают :(
// Yii2Rulez!
astronin
Сообщения: 606
Зарегистрирован: 2012.01.30, 17:46

Re: apidoc class @property

Сообщение astronin »

сори, почему-то не заметил
unclead
Сообщения: 160
Зарегистрирован: 2015.03.13, 19:44

Re: apidoc class @property

Сообщение unclead »

ну и, в общем, даже для сгенеренной с помощью gii модельки(там есть phpdoc описания столбцов таблицы) - и они тоже в доки не попадают :(
предлагаю оформить это все в виде Issue на github
fly2k
Сообщения: 155
Зарегистрирован: 2013.03.19, 05:31

Re: apidoc class @property

Сообщение fly2k »

unclead писал(а):предлагаю оформить это все в виде Issue на github
https://github.com/yiisoft/yii2-apidoc/issues/7

с инглишом не ахти, так что помогайте, если кому интересно.
// Yii2Rulez!
unclead
Сообщения: 160
Зарегистрирован: 2015.03.13, 19:44

Re: apidoc class @property

Сообщение unclead »

с инглишом не ахти, так что помогайте, если кому интересно.
не стоит заморачиваться на эту тему. Главное, чтобы смысл был понятен. Создание issue о проблеме уже вклад в развитие фреймворка.
А если сможете сделать pull request, так это будет вообще здорово ;)
Аватара пользователя
root
Сообщения: 3
Зарегистрирован: 2013.06.07, 19:18
Контактная информация:

Re: apidoc class @property

Сообщение root »

Так и не решили Issue, попрежнему @property не добавляет :cry:
Ответить