"La documentazione è parte del progetto, così come il codice sorgente ed i test!"
"La documentazione vive nel repository insieme al codice sorgente ed ai test!"
Codice scritto con uno stile adeguato di programmazione è più facile da documentare:
High coesion, low coupling
I commenti non sono sistemi per la revisione del codice
/**
* method name: pityTheFoo
* created: May 18, 2016 11:33PM
* Author: Bob
* Revisions: Sue (5/16/2009) - Lengthened monkey's arms
* Bob (5/17/2009) - Solved drooling issue
*/
function pityTheFoo() {
...
}
Evitare i commenti quando il codice è self-documented
// Loop through all bananas in the bunch
foreach(banana b in bunch) {
monkey.eat(b); //make the monkey eat one banana
}
JSDoc è tool per la generazione di documentazione API per JavaScript, simile a JavaDoc o PHPDoc
/**
/*
o per /***
vengono ignorati/**
* This is a description of the foo function.
*/
function foo() {
}
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {
}
JSDoc supporta due tipi di tag:
Block tags
@
/**
* @contructor
* @param {string} title - The title of the book.
* @return {string} the result
*/
Inline tags
@
{
e }
/**
* See {@link Person#say method}
*/
/** @constructor */
Person = function() {
this.say = function() {
return "I'm an instance.";
}
function say() {
return "I'm inner.";
}
}
Person.say = function() {
return "I'm static.";
}
var p = new Person();
p.say(); // I'm an instance.
Person.say(); // I'm static.
Nei commenti possiamo riferirci ai membri come segue:
Person#say // the instance method named "say."
Person.say // the static method named "say."
Person~say // the inner method named "say."
Usando il tag @link
/**
* See {@link Person}
* and [Person's say instance method]{@link Person#say}.
* Also, check out {@link http://www.google.com|Google} and
* {@link https://github.com GitHub}.
*/
function myFunction() {}
Il tag {@link}
crea un link
ad un namepath o ad un URL specificato
Per generare la documentazione si usa il tool a linea di comando:
$> jsdoc <path-to-source-files>
./out
$> jsdoc src/*.js -d docs
./docs
Il file README.md costituisce la front page della documentazione HTML generata. E' un file in scritto in markdown e si può includere in due modi:
$> jsdoc src/*.js -R path/to/README.md
Per personalizzare il comportamento di JSDoc si può fornire un file di configurazione in formato JSON
utilizzando l'opzione -c, per esempio jsdoc -c /path/to/conf.json
{
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"source": {
"includePattern": ".+\\.js(doc)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": [],
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
JSDoc fornisce un solo template grafico per la documentazione HTML generata, ma esistono diversi template che possono essere configurati ed installati
Nel progetto ci sarà tipicamente un file package.json in cui descrivere ed elencare tutti i pacchetti npm di cui abbiamo bisogno come dipendenza
{
"name": "MyApplication",
"version": "1.0.0",
"description": "This is my application",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"author": "francesco.valente@alcacoop.it",
"license": "ISC",
"dependencies": {
"underscore": "~1.8.3",
"express": "~4.13.3",
"mustache": "~2.1.3",
"socket.io": "~1.3.7"
},
"devDependencies": {
"grunt-contrib-jshint": "~0.11.3",
"grunt-contrib-cssmin": "~0.14.0",
"grunt-contrib-uglify": "~0.9.2",
"grunt-contrib-watch": "~0.6.1",
"grunt-sass": "~1.1.0-beta",
"grunt-contrib-connect": "~0.11.2",
"grunt-zip": "~0.17.1",
"grunt": "~0.4.5",
}
}
Dopo aver installato NodeJS ed NPM:
$> npm install --save-dev jsdoc
# Optional
$> npm install --save-dev minami
Alca Società Cooperativa http://alcacoop.it
Released under CC BY-NC-SA 3.0