Все официальные примеры 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)... или действительно любых длинных строк аннотаций, если на то пошло.