From a9bd48161269321948ee7d8f5009c41bccac198f Mon Sep 17 00:00:00 2001 From: Zearin Date: Sun, 6 Feb 2022 12:54:44 -0500 Subject: [PATCH] docs(src/io): Use `describe()` instead of `@alt` Addresses #5139 --- src/io/files.js | 63 +++++++++++++++------------------ src/io/p5.Table.js | 81 +++++++++++++++---------------------------- src/io/p5.TableRow.js | 29 ++++++---------- src/io/p5.XML.js | 5 ++- 4 files changed, 67 insertions(+), 111 deletions(-) diff --git a/src/io/files.js b/src/io/files.js index 49ae034753..656cc26e2f 100644 --- a/src/io/files.js +++ b/src/io/files.js @@ -69,6 +69,8 @@ import '../core/friendly_errors/fes_core'; * ellipse(width / 2, height / 2, earthquakeMag * 10, earthquakeMag * 10); * textAlign(CENTER); * text(earthquakeName, 0, height - 30, width, 30); + * describe(`50×50 ellipse that changes from black to white + * depending on the current humidity`); * } * * @@ -85,6 +87,8 @@ import '../core/friendly_errors/fes_core'; * * function draw() { * background(200); + * describe(`50×50 ellipse that changes from black to white + * depending on the current humidity`); * } * * function drawEarthquake(earthquakes) { @@ -96,10 +100,6 @@ import '../core/friendly_errors/fes_core'; * text(earthquakeName, 0, height - 30, width, 30); * } * - * - * @alt - * 50×50 ellipse that changes from black to white depending on the current humidity - * 50×50 ellipse that changes from black to white depending on the current humidity */ /** * @method loadJSON @@ -217,6 +217,8 @@ p5.prototype.loadJSON = function(...args) { * function setup() { * background(200); * text(random(result), 10, 10, 80, 80); + * describe(`randomly generated text from a file, + * for example "i smell like butter"`); * } * * @@ -226,6 +228,8 @@ p5.prototype.loadJSON = function(...args) { *
* function setup() { * loadStrings('assets/test.txt', pickString); + * describe(`randomly generated text from a file, + * for example "i have three feet"`); * } * * function pickString(result) { @@ -233,10 +237,6 @@ p5.prototype.loadJSON = function(...args) { * text(random(result), 10, 10, 80, 80); * } *
- * - * @alt - * randomly generated text from a file, for example "i smell like butter" - * randomly generated text from a file, for example "i have three feet" */ p5.prototype.loadStrings = function(...args) { p5._validateParameters('loadStrings', args); @@ -364,13 +364,11 @@ p5.prototype.loadStrings = function(...args) { * for (let c = 0; c < table.getColumnCount(); c++) { * print(table.getString(r, c)); * } + * describe(`randomly generated text from a file, + * for example "i smell like butter"`); * } * * - * - * @alt - * randomly generated text from a file, for example "i smell like butter" - * randomly generated text from a file, for example "i have three feet" */ p5.prototype.loadTable = function(path) { // p5._validateParameters('loadTable', arguments); @@ -634,6 +632,7 @@ function makeObject(row, headers) { * let name = children[i].getContent(); * print(id + ', ' + coloring + ', ' + name); * } + * describe(`no image displayed`); * } * * // Sketch prints: @@ -641,9 +640,6 @@ function makeObject(row, headers) { * // 1, Panthera pardus, Leopard * // 2, Equus zebra, Zebra * - * - * @alt - * no image displayed */ p5.prototype.loadXML = function(...args) { const ret = new p5.XML(); @@ -712,11 +708,9 @@ p5.prototype.loadXML = function(...args) { * for (let i = 0; i < 5; i++) { * console.log(data.bytes[i].toString(16)); * } + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.prototype.loadBytes = function(file, callback, errorCallback) { const ret = {}; @@ -1434,18 +1428,21 @@ p5.PrintWriter = function(filename, extension) { * * // Saves the canvas as an image by default * save('myCanvas.jpg'); + * describe(`An example for saving a canvas as an image.`); * * - *
+ *
* // Saves p5.Image as an image * img = createImage(10, 10); * save(img, 'myImage.png'); + * describe(`An example for saving a p5.Image element as an image.`); *
* *
* // Saves p5.Renderer object as an image * obj = createGraphics(100, 100); * save(obj, 'myObject.png'); + * describe(`An example for saving a p5.Renderer element.`); *
* *
@@ -1458,6 +1455,9 @@ p5.PrintWriter = function(filename, extension) { * * // Tab Separated Values * save(myTable, 'myTable.tsv'); + * + * describe(`An example showing how to save a table in formats of + * HTML, CSV and TSV.`); *
* *
@@ -1468,21 +1468,17 @@ p5.PrintWriter = function(filename, extension) { * * // Optimizes JSON filesize * save(myJSON, 'my.json', true); + * + * describe(`An example for saving JSON to a txt file with some extra arguments.`); *
* *
* // Saves array of strings to text file with line breaks after each item * let arrayOfStrings = ['a', 'b']; * save(arrayOfStrings, 'my.txt'); + * describe(`An example for saving an array of strings to text file + * with line breaks.`); *
- * - * @alt - * An example for saving a canvas as an image. - * An example for saving a p5.Image element as an image. - * An example for saving a p5.Renderer element. - * An example showing how to save a table in formats of HTML, CSV and TSV. - * An example for saving JSON to a txt file with some extra arguments. - * An example for saving an array of strings to text file with line breaks. */ p5.prototype.save = function(object, _filename, _options) { @@ -1556,6 +1552,7 @@ p5.prototype.save = function(object, _filename, _options) { * createCanvas(100, 100); * background(200); * text('click here to save', 10, 10, 70, 80); + * describe(`no image displayed`); * } * * function mousePressed() { @@ -1571,9 +1568,6 @@ p5.prototype.save = function(object, _filename, _options) { * // "name": "Lion" * // } *
- * - * @alt - * no image displayed */ p5.prototype.saveJSON = function(json, filename, opt) { p5._validateParameters('saveJSON', arguments); @@ -1610,6 +1604,7 @@ p5.prototype.saveJSONArray = p5.prototype.saveJSON; * createCanvas(100, 100); * background(200); * text('click here to save', 10, 10, 70, 80); + * describe(`no image displayed`); * } * * function mousePressed() { @@ -1625,9 +1620,6 @@ p5.prototype.saveJSONArray = p5.prototype.saveJSON; * // cat * // dog * - * - * @alt - * no image displayed */ p5.prototype.saveStrings = function(list, filename, extension, isCRLF) { p5._validateParameters('saveStrings', arguments); @@ -1682,15 +1674,14 @@ function escapeHelper(content) { * * // To save, un-comment next line then click 'run' * // saveTable(table, 'new.csv'); + * + * describe(`no image displayed`); * } * * // Saves the following to a file called 'new.csv': * // id,species,name * // 0,Panthera leo,Lion * - * - * @alt - * no image displayed */ p5.prototype.saveTable = function(table, filename, options) { p5._validateParameters('saveTable', arguments); diff --git a/src/io/p5.Table.js b/src/io/p5.Table.js index 9dc0f6d286..b4be8220ad 100644 --- a/src/io/p5.Table.js +++ b/src/io/p5.Table.js @@ -125,12 +125,11 @@ p5.Table = function(rows) { * for (let r = 0; r < table.getRowCount(); r++) * for (let c = 0; c < table.getColumnCount(); c++) * print(table.getString(r, c)); + * + * describe(`no image displayed`); * } * * - * - * @alt - * no image displayed */ p5.Table.prototype.addRow = function(row) { // make sure it is a valid TableRow @@ -178,12 +177,11 @@ p5.Table.prototype.addRow = function(row) { * for (let r = 0; r < table.getRowCount(); r++) * for (let c = 0; c < table.getColumnCount(); c++) * print(table.getString(r, c)); + * + * describe(`no image displayed`); * } * * - * - * @alt - * no image displayed */ p5.Table.prototype.removeRow = function(id) { this.rows[id].table = null; // remove reference to table @@ -226,12 +224,11 @@ p5.Table.prototype.removeRow = function(id) { * for (let c = 0; c < table.getColumnCount(); c++) { * print(row.getString(c)); * } + * + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.getRow = function(r) { return this.rows[r]; @@ -274,12 +271,11 @@ p5.Table.prototype.getRow = function(r) { * for (let r = 0; r < table.getRowCount(); r++) * for (let c = 0; c < table.getColumnCount(); c++) * print(table.getString(r, c)); + * + * describe(`no image displayed`); * } * * - * - * @alt - * no image displayed */ p5.Table.prototype.getRows = function() { return this.rows; @@ -322,12 +318,10 @@ p5.Table.prototype.getRows = function() { * let row = table.findRow('Zebra', 'name'); * //find the corresponding species * print(row.getString('species')); + * describe(`no image displayed`); * } * * - * - * @alt - * no image displayed */ p5.Table.prototype.findRow = function(value, column) { // try the Object @@ -391,12 +385,10 @@ p5.Table.prototype.findRow = function(value, column) { * //find the rows containing animals named Goat * let rows = table.findRows('Goat', 'name'); * print(rows.length + ' Goats found'); + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.findRows = function(value, column) { const ret = []; @@ -573,12 +565,10 @@ p5.Table.prototype.matchRows = function(regexp, column) { * //getColumn returns an array that can be printed directly * print(table.getColumn('species')); * //outputs ["Capra hircus", "Panthera pardus", "Equus zebra"] + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.getColumn = function(value) { const ret = []; @@ -623,12 +613,10 @@ p5.Table.prototype.getColumn = function(value) { * table.clearRows(); * print(table.getRowCount() + ' total rows in table'); * print(table.getColumnCount() + ' total columns in table'); + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.clearRows = function() { delete this.rows; @@ -673,12 +661,11 @@ p5.Table.prototype.clearRows = function() { * for (let r = 0; r < table.getRowCount(); r++) * for (let c = 0; c < table.getColumnCount(); c++) * print(table.getString(r, c)); + * + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.addColumn = function(title) { const t = title || null; @@ -925,12 +912,10 @@ p5.Table.prototype.trim = function(column) { * function setup() { * table.removeColumn('id'); * print(table.getColumnCount()); + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.removeColumn = function(c) { let cString; @@ -995,12 +980,11 @@ p5.Table.prototype.removeColumn = function(c) { * for (let r = 0; r < table.getRowCount(); r++) * for (let c = 0; c < table.getColumnCount(); c++) * print(table.getString(r, c)); + * + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.set = function(row, column, value) { this.rows[row].set(column, value); @@ -1041,12 +1025,11 @@ p5.Table.prototype.set = function(row, column, value) { * * print(table.getColumn(0)); * //["0", 1, "2"] + * + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.setNum = function(row, column, value) { this.rows[row].setNum(column, value); @@ -1087,11 +1070,10 @@ p5.Table.prototype.setNum = function(row, column, value) { * newRow.setString('name', 'Wolf'); * * print(table.getArray()); + * + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.Table.prototype.setString = function(row, column, value) { this.rows[row].setString(column, value); @@ -1132,12 +1114,10 @@ p5.Table.prototype.setString = function(row, column, value) { * //Capra hircus * print(table.get(0, 'species')); * //Capra hircus + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.get = function(row, column) { return this.rows[row].get(column); @@ -1176,12 +1156,10 @@ p5.Table.prototype.get = function(row, column) { * function setup() { * print(table.getNum(1, 0) + 100); * //id 1 + 100 = 101 + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.getNum = function(row, column) { return this.rows[row].getNum(column); @@ -1227,12 +1205,10 @@ p5.Table.prototype.getNum = function(row, column) { * print(table.getString(2, 0)); // 2 * print(table.getString(2, 1)); // Equus zebra * print(table.getString(2, 2)); // Zebra + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.getString = function(row, column) { @@ -1273,12 +1249,11 @@ p5.Table.prototype.getString = function(row, column) { * * print(tableObject); * //outputs an object + * + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.getObject = function(headerColumn) { const tableObject = {}; @@ -1332,12 +1307,10 @@ p5.Table.prototype.getObject = function(headerColumn) { * for (let i = 0; i < tableArray.length; i++) { * print(tableArray[i]); * } + * describe(`no image displayed`); * } * * - * - *@alt - * no image displayed */ p5.Table.prototype.getArray = function() { const tableArray = []; diff --git a/src/io/p5.TableRow.js b/src/io/p5.TableRow.js index d13b131bbb..016cb7b57d 100644 --- a/src/io/p5.TableRow.js +++ b/src/io/p5.TableRow.js @@ -71,11 +71,10 @@ p5.TableRow = function(str, separator) { * * //print the results * print(table.getArray()); + * + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.TableRow.prototype.set = function(column, value) { // if typeof column is string, use .obj @@ -132,11 +131,10 @@ p5.TableRow.prototype.set = function(column, value) { * } * * print(table.getArray()); + * + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.TableRow.prototype.setNum = function(column, value) { const floatVal = parseFloat(value); @@ -177,11 +175,10 @@ p5.TableRow.prototype.setNum = function(column, value) { * } * * print(table.getArray()); + * + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.TableRow.prototype.setString = function(column, value) { const stringVal = value.toString(); @@ -222,11 +219,10 @@ p5.TableRow.prototype.setString = function(column, value) { * } * * print(names); + * + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.TableRow.prototype.get = function(column) { if (typeof column === 'string') { @@ -272,11 +268,9 @@ p5.TableRow.prototype.get = function(column) { * maxId = min(maxId, id); * } * print('minimum id = ' + minId + ', maximum id = ' + maxId); + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.TableRow.prototype.getNum = function(column) { let ret; @@ -329,11 +323,10 @@ p5.TableRow.prototype.getNum = function(column) { * } * * print('longest: ' + longest); + * + * describe(`no image displayed`); * } * - * - * @alt - * no image displayed */ p5.TableRow.prototype.getString = function(column) { if (typeof column === 'string') { diff --git a/src/io/p5.XML.js b/src/io/p5.XML.js index ac6e96f677..acd2d86415 100644 --- a/src/io/p5.XML.js +++ b/src/io/p5.XML.js @@ -39,6 +39,8 @@ import p5 from '../core/main'; * let name = children[i].getContent(); * print(id + ', ' + coloring + ', ' + name); * } + * + * describe(`no image displayed`); * } * * // Sketch prints: @@ -46,9 +48,6 @@ import p5 from '../core/main'; * // 1, Panthera pardus, Leopard * // 2, Equus zebra, Zebra * - * - * @alt - * no image displayed */ p5.XML = function(DOM) { if (!DOM) {