Joan a 23:59, 27 març 2022

2022-03-27T23:59:13Z

Joan: /* Generar la documentació */

2022-03-27T23:58:17Z

Generar la documentació

Joan: Es crea la pàgina amb «=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 program...».

2022-03-27T23:57:14Z

Es crea la pàgina amb «=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 program...».

Pàgina nova

=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'':
<pre>
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);
</pre>

script ''canvas.js'':
<pre>
/** @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 };
</pre>

script ''square.js'':
<pre>
/** @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;
</pre>
=Generar la documentació=
Per generar la documentació, fem servir l'eina ''jsdoc''. La instal·lem amb ''npm'' de forma global:
<pre>
$ npm install -g jsdoc
</pre>
I per generar la documentació en la carpeta ''square-doc'':
<pre>
$ jsdoc -d square-doc main.js ./modules/canvas.js ./modules/square.js
</pre>
A dins la carpeta tenim el fitxer index.html que és el punt d'entrada de tota la documentació.

@@ Línia 1: / Línia 1: @@
 =Introducció=
 https://jsdoc.app
 Amb JSDoc podem documentar fàcilment els nostres projectes javascript.

@@ Línia 180: / Línia 180: @@
 $ jsdoc -d square-doc main.js ./modules/canvas.js ./modules/square.js
 </pre>
-A dins la carpeta tenim el fitxer index.html que és el punt d'entrada de tota la documentació.
+A dins la carpeta tenim el fitxer index.html que és el punt d'entrada de tota la documentació, en format HTML.

JSDoc: documentació amb Javascript - Historial de revisió

Joan a 23:59, 27 març 2022

Joan: /* Generar la documentació */

Joan: Es crea la pàgina amb «=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 program...».