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.