JSDoc: documentació amb Javascript

Introducció

https://jsdoc.app Amb JSDoc podem documentar fàcilment els nostres projectes javascript.

A l'assignatura de M06 hem fet la petita pràctica de programació amb mòduls: canvas, quadrats i cercles. Anem a documentar els mòduls i el codi que hem creat.

Codi amb comentaris

El codi documentat queda de la següent manera:

script main.js:

import { create, createReportList } from './modules/canvas.js';
import { name, draw, reportArea, reportPerimeter } from './modules/square.js';
import randomSquare from './modules/square.js';

/** variable myCanvas: creem el quadrat principal */
let myCanvas = create('myCanvas', document.body, 480, 320);

/** variable reportList: creem la llista on mostrarem la informació */
let reportList = createReportList(myCanvas.id);

/**
variable square1: creem el primer quadrat
*/
let square1 = draw(myCanvas.ctx, 50, 50, 100, 'blue');

/**
reportem informació sobre square1
*/
reportArea(square1.length, reportList);
reportPerimeter(square1.length, reportList);

/**
variable square1: creem el segon quadrat de tipus aleatori
*/
let square2 = randomSquare(myCanvas.ctx);

script canvas.js:

/** @module canvas */

/**
 * Crea el canvas.
 * @param {string} L'identificador que tindrà el canvas.
 * @param {ele} parent - referència al parent que contindrà el canvas.
 * @param {int} width - Amplada del canvas.
 * @param {int} height - Altura del canvas.
 * @return {obj} Retorna un objecte amb les propietats ctx com a referència del canvas que s'ha creat, i id del div que s'ha creat.
 */
function create(id, parent, width, height) {
  let divWrapper = document.createElement('div');
  let canvasElem = document.createElement('canvas');
  parent.appendChild(divWrapper);
  divWrapper.appendChild(canvasElem);

  divWrapper.id = id;
  canvasElem.width = width;
  canvasElem.height = height;

  let ctx = canvasElem.getContext('2d');

  return {
    ctx: ctx,
    id: id
  };
}

/**
 * Crea un element ul, que servirà per contenir la llista amb informació del quadrat.
 * @param {wrapperId} wrapperId - El id del canvas al qual fem referència.
 * @return {listID} listID - Referència a la llista HTML que està creada.
 */
function createReportList(wrapperId) {
  let list = document.createElement('ul');
  list.id = wrapperId + '-reporter';

  let canvasWrapper = document.getElementById(wrapperId);
  canvasWrapper.appendChild(list);

  return list.id;
}

export { create, createReportList };

script square.js:

/** @module square */

/** El nom del mòdul. */
const name = 'square';

/**
 * Dibuixar un quadrat.
 * @param {ctx} El context del canvas.
 * @param {int} length - Longitud del quadrat.
 * @param {int} x - Posició x del quadrat (superior esquerre).
 * @param {int} y - Posició y del quadrat (superior esquerre).
 * @param {string} El color de fons del quadrat.
 * @return {obj} Retorna un objecte amb les propietats length, x, y, color.
 */
function draw(ctx, length, x, y, color) {
  ctx.fillStyle = color;
  ctx.fillRect(x, y, length, length);

  return {
    length: length,
    x: x,
    y: y,
    color: color
  };
}

function random(min, max) {
   let num = Math.floor(Math.random() * (max - min)) + min;
   return num;
}

/**
 * Crea un element li, amb el contingut de l'àrea, i l'afegeix a la llista existent.
 * @param {int} lenght - Longitud del quadrat.
 * @param {listID} listID - Referència a la llista HTML que està creada.
 */
function reportArea(length, listId) {
  let listItem = document.createElement('li');
  listItem.textContent = `${name} area is ${length * length}px squared.`

  let list = document.getElementById(listId);
  list.appendChild(listItem);
}

/**
 * Crea un element li, amb el contingut del perímetre, i l'afegeix a la llista existent.
 * @param {int} lenght - Longitud del quadrat.
 * @param {listID} listID - Referència a la llista HTML que està creada.
 */
function reportPerimeter(length, listId) {
  let listItem = document.createElement('li');
  listItem.textContent = `${name} perimeter is ${length * 4}px.`

  let list = document.getElementById(listId);
  list.appendChild(listItem);
}

/**
 * Dibuixar un quadrat aleatori.
 * @param {ctx} El context del canvas.
 * @return {obj} Retorna un objecte amb les propietats length, x, y, color, que prenen valors aleatoris.
 */
function randomSquare(ctx) {
  let color1 = random(0, 255);
  let color2 = random(0, 255);
  let color3 = random(0, 255);
  let color = `rgb(${color1},${color2},${color3})`
  ctx.fillStyle = color;

  let x = random(0, 480);
  let y = random(0, 320);
  let length = random(10, 100);
  ctx.fillRect(x, y, length, length);

  return {
    length: length,
    x: x,
    y: y,
    color: color
  };
}

export { name, draw, reportArea, reportPerimeter };
export default randomSquare;

Generar la documentació

Per generar la documentació, fem servir l'eina jsdoc. La instal·lem amb npm de forma global:

$ npm install -g jsdoc

I per generar la documentació en la carpeta square-doc:

$ jsdoc -d square-doc main.js ./modules/canvas.js ./modules/square.js

A dins la carpeta tenim el fitxer index.html que és el punt d'entrada de tota la documentació, en format HTML.