Каково правильное/каноническое форматирование длинных строк JSDoc?

Все официальные примеры JSDoc имеют наивно простые строки документации, например:

/**
 * @param {string} author - The author of the book.
 */

Проблема заключается в том, что в реальной документации вы часто имеете более длинные строки документации:

/**
 * @param {string} author - The author of the book, presumably some person who writes well
 */

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

Я мог бы сделать:

/**
 * @param {string} author - The author of the book, presumably some
 * person who writes well
 */

Но это трудно читать. Вместо этого я мог бы сделать:

/**
 * @param {string} author - The author of the book, presumably some
 *                          person who writes well
 */

Это выглядит лучше, но это может привести к тонне строк, особенно если параметр имеет длинное имя:

/**
 * @param {string} personWhoIsTheAuthorOfTheBook - The author of the
 *                                                 book, presumably
 *                                                 some person who
 *                                                 writes well
 */

Итак, мой вопрос в том, каков правильный/официальный/канонический способ форматирования длинных строк @param (в коде, а не в сгенерированном JSDoc)... или действительно какие-то длинные строки аннотаций, если на то пошло.

Ответы

Ответ 1

Существует два правильных способа решения разрывов строк в JSDoc. Первым, по-видимому, используемым Google, является отступ строк после первого:

/**
 * @param {string} author - The author of the book, presumably some
 *     person who writes well and does so for a living. This is
 *     especially important for obvious reasons.
 */

Это руководство по стилю Google Javascript: http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments

Вторая основана на том факте, что JSDoc получен из JavaDoc, который похож на ваш второй пример. См. Следующую ссылку для примеров JavaDoc: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

Я бы рекомендовал использовать метод отступов - я думаю, что это хороший крест между читабельностью и отсутствием очень коротких строк.