Ho appena pubblicato un post sul mio blog in inglese per sostenere la necessità di utilizzare i commenti JSDoc nello sviluppo di plugin per jQuery. Allo stato attuale i plugin vengono commentati così come piace all'autore, senza cioè seguire uno standard comune che possa facilitare chi voglia riusare il plugin o modificarlo. Il risultato finale è quello di avere dei commenti del tutto confusi e che costringono ogni volta l'utente a reimparare da zero lo stile dell'autore nella scrittura del codice.
I plugin jQuery, che dovrebbero essere aperti e modificabili, si rivelano troppo spesso essere chiusi, ermetici e scarsamente adattabili. Questo perchè nel codice non ci sono spesso riferimenti utili che possano guidare nel riutilizzo del plugin.
Per esempio, all'inizio del file si potrebbe usare JSDoc in questo modo:
/** @fileoverview jTweet - A jQuery plugin for Twitter
* @author Gabriele Romanato
* @version 1.0
* @requires jQuery
*/
Per un metodo privato del plugin, invece, si potrebbe scrivere:
/** Turns a textual URL into an HTML link
* @private
* @param {String} url The textual URL
* @returns {String} link The HTML link
*/
function formatTwitterURLs(url) {
// ...
return link;
}
Spero che queste osservazioni vengano recepite dagli autori di plugin, in modo da migliorare la situazione esistente.