Как документировать методы Vue, если метод возвращает this?
Простой пример:
/**
* Тут описание метода
*
* @param {number} id
* @return {this}
*/
myMethod(id) {
// ...do something
return this;
},
Варианты документации:
/**
*
...
* @return {this}
*/
Так:
/**
*
...
* @return {Object} this
*/
Или так:
/**
*
...
* @return {Object} this - VueComponent
*/
Как правильно? Или как документируете вы?
Ответы (1 шт):
Я не видел, чтобы была возможность в @returns указать, что возвращаться будет this метода, только тип и короткое описание. Если нужно сообщить, что функция вернёт свой this, то можно текстом указать это в описании функции.
А вообще обычно достаточно указать только тип и не более. Если к примеру Вы пишите Vector2 или Complex, Quaternion, то такие вещи разумный программист создаёт Неизменяемыми. В таком случае все операции над экземплярами этих классов всегда отдают новый объект.
Это сделано из соображения безопасности: в любой момент ссылка на объект может быть скопирована, затем в одном месте цепочка расчётов продолжается, а в другом необходимо просто хранить промежуточное значение. Сделали объект модифицируемым - одна чать программы любезно и незаметно побьёт данные в другой части. А ты бегай потом с дебаггером и соображай.