Qual è la formattazione corretta/canonica delle lunghe linee JSDoc?

Question

Tutti gli esempi ufficiali JSDoc hanno ingenuamente semplici stringhe di documentazione, come la seguente:

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

Il problema è, nella documentazione della vita reale si ha spesso più lunghe stringhe di documentazione:

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

ma dal momento che la maggior parte delle aziende (per motivi legittimi di leggibilità) hanno limiti di lunghezza della linea, spesso non è accettabile. Tuttavia, quello che non riesco a capire è quale dovrebbe essere il modo "giusto" per spezzare quelle linee.

ho potuto fare:

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

ma che è difficile da leggere. Potrei invece faccio:

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

che sembra migliore, ma può portare a una tonnellata di linee, specialmente se il parametro ha un nome lungo:

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

Quindi la mia domanda è, qual è il modo corretto/ufficiale/canonico di formattare lunghe righe @param (nel codice, non nel JSDoc generato) ... o in realtà qualsiasi linea di annotazione lunga per quella materia.

Answer 1

Esistono due metodi adeguati per gestire le interruzioni di riga in JSDoc. Il primo, a quanto pare utilizzato da Google, è quello di far rientrare le righe dopo la prima:

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

Questo è dal Style Guide di Google Javascript: http://google.github.io/styleguide/javascriptguide.xml?showone=Comments#Comments

Il secondo si basa sul fatto che JSDoc deriva da JavaDoc, che è simile al tuo secondo esempio. Vedere il seguente collegamento per gli esempi JavaDoc: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

Si consiglia di utilizzare il metodo di indentazione - Penso che sia un buon incrocio tra la leggibilità e non avere linee estremamente brevi.