Quelle est la mise en forme correcte / canonique des longues lignes JSDoc?
Tous les exemples officiels de JSDoc ont des chaînes de documentation naïvement simples, comme les suivantes:
/**
* @param {string} author - The author of the book.
*/
Le problème est que, dans la documentation réelle, vous avez souvent des chaînes de documentation plus longues:
/**
* @param {string} author - The author of the book, presumably some person who writes well
*/
Mais comme la plupart des entreprises (pour des raisons de lisibilité légitimes) ont des limites de longueur de ligne, ce qui précède n'est souvent pas acceptable. Cependant, ce que je ne peux pas comprendre, c'est quelle devrait être la "bonne" façon de briser ces lignes.
Je pourrais faire:
/**
* @param {string} author - The author of the book, presumably some
* person who writes well
*/
Mais c'est difficile à lire. Je pourrais plutôt faire:
/**
* @param {string} author - The author of the book, presumably some
* person who writes well
*/
Cela semble mieux, mais cela peut entraîner une tonne de lignes, surtout si le paramètre a un nom long:
/**
* @param {string} personWhoIsTheAuthorOfTheBook - The author of the
* book, presumably
* some person who
* writes well
*/
Donc, ma question est, quelle est la bonne façon/officielle/canonique de formater long @param lignes (dans le code, pas dans le JSDoc généré) ... ou vraiment toutes les longues lignes d'annotation d'ailleurs.
Il existe deux façons appropriées de traiter les sauts de ligne dans JSDoc. Le premier, apparemment utilisé par Google, consiste à mettre en retrait les lignes après le premier:
/**
* @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.
*/
Ceci provient du guide de style Google Javascript: http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments
Le second est basé sur le fait que JSDoc est dérivé de JavaDoc, qui est similaire à votre deuxième exemple. Voir le lien suivant pour des exemples JavaDoc: http://www.Oracle.com/technetwork/Java/javase/documentation/index-137868.html#styleguide
Je recommanderais d'utiliser la méthode d'indentation - je pense que c'est un bon croisement entre la lisibilité et le fait de ne pas avoir de lignes extrêmement courtes.