node - jsdoc tutorial

¿Cuál es el formato correcto/canónico de líneas JSDoc largas?

Question

Todos los ejemplos oficiales de JSDoc tienen cadenas de documentación ingenuamente simples, como las siguientes:

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

El problema es que, en la documentación de la vida real, a menudo tienes cadenas de documentación más largas:

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

Pero como la mayoría de las empresas (por razones de legibilidad legítima) tienen límites de longitud de línea, lo anterior a menudo no es aceptable. Sin embargo, lo que no puedo entender es cuál debería ser la forma "correcta" de romper esas líneas.

Yo podría hacer:

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

Pero eso es difícil de leer. En su lugar podría hacer:

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

Eso se ve mejor, pero puede resultar en una tonelada de líneas, especialmente si el parámetro tiene un nombre largo:

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

Entonces, mi pregunta es, ¿cuál es la forma correcta / oficial / canónica de formatear líneas largas @param (en el código, no en el JSDoc generado) ... o en realidad cualquier línea larga de anotación?

Answer 1

Hay dos formas adecuadas de tratar los saltos de línea en JSDoc. La primera, aparentemente utilizada por Google, es sangrar las líneas después de la primera:

/**
* @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.
*/

Esto es de la Guía de estilo de Google Javascript: http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments

El segundo se basa en el hecho de que JSDoc se deriva de JavaDoc, que es similar a su segundo ejemplo. Consulte el siguiente enlace para ver ejemplos de JavaDoc: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

Recomendaría usar el método de sangrado: creo que es un buen cruce entre la legibilidad y no tener líneas extremadamente cortas.