various javaDoc improvements

src/public/app/services/frontend_script_api.js

@@ -437,6 +437,15 @@ function FrontendScriptApi(startNote, currentNote, originEntity = null, $contain
      * @param includedNoteId - noteId of the included note
      */
     this.refreshIncludedNote = includedNoteId => appContext.triggerEvent('refreshIncludedNote', {noteId: includedNoteId});
+
+    /**
+     * Return randomly generated string of given length. This random string generation is NOT cryptographically secure.
+     *
+     * @method
+     * @param {number} length of the string
+     * @returns {string} random string
+     */
+    this.randomString = utils.randomString;
 }
 
 export default FrontendScriptApi;

src/services/backend_script_api.js

@@ -33,10 +33,14 @@ function BackendScriptApi(currentNote, apiParams) {
         this[key] = apiParams[key];
     }
 
+    /** @property {axios} Axios library for HTTP requests. See https://axios-http.com/ for documentation */
     this.axios = axios;
+    /** @property {dayjs} day.js library for date manipulation. See https://day.js.org/ for documentation */
     this.dayjs = dayjs;
+    /** @property {axios} xml2js library for XML parsing. See https://github.com/Leonidas-from-XIV/node-xml2js for documentation */
     this.xml2js = xml2js;
 
+    // DEPRECATED - use direct api.unescapeHtml
     this.utils = {
         unescapeHtml: utils.unescapeHtml
     };
@@ -192,7 +196,7 @@ function BackendScriptApi(currentNote, apiParams) {
      * @param {string} parentNoteId
      * @param {string} title
      * @param {string} content
-     * @return {{note: Note, branch: Branch}}
+     * @return {{note: Note, branch: Branch}} - object having "note" and "branch" keys representing respective objects
      */
     this.createTextNote = (parentNoteId, title, content = '') => noteService.createNewNote({
         parentNoteId,
@@ -208,7 +212,7 @@ function BackendScriptApi(currentNote, apiParams) {
      * @param {string} parentNoteId
      * @param {string} title
      * @param {object} content
-     * @return {{note: Note, branch: Branch}}
+     * @return {{note: Note, branch: Branch}} object having "note" and "branch" keys representing respective objects
      */
     this.createDataNote = (parentNoteId, title, content = {}) => noteService.createNewNote({
         parentNoteId,
@@ -391,6 +395,32 @@ function BackendScriptApi(currentNote, apiParams) {
      */
     this.transactional = sql.transactional;
 
+    /**
+     * Return randomly generated string of given length. This random string generation is NOT cryptographically secure.
+     *
+     * @method
+     * @param {number} length of the string
+     * @returns {string} random string
+     */
+    this.randomString = utils.randomString;
+
+    /**
+     * @method
+     * @param {string} string to escape
+     * @returns {string} escaped string
+     */
+    this.escapeHtml = utils.escapeHtml;
+
+    /**
+     * @method
+     * @param {string} string to unescape
+     * @returns {string} unescaped string
+     */
+    this.unescapeHtml = utils.unescapeHtml;
+
+    /**
+     * @property {module:sql} sql
+     */
     this.sql = sql;
 
     /**

src/services/sql.js

@@ -1,5 +1,9 @@
 "use strict";
 
+/**
+ * @module sql
+ */
+
 const log = require('./log');
 const Database = require('better-sqlite3');
 const dataDir = require('./data_dir');
@@ -273,14 +277,67 @@ module.exports = {
     dbConnection,
     insert,
     replace,
+
+    /**
+     * Get single value from the given query - first column from first returned row.
+     *
+     * @method
+     * @param {string} query - SQL query with ? used as parameter placeholder
+     * @param {object[]} [params] - array of params if needed
+     * @return [object] - single value
+     */
     getValue,
+
+    /**
+     * Get first returned row.
+     *
+     * @method
+     * @param {string} query - SQL query with ? used as parameter placeholder
+     * @param {object[]} [params] - array of params if needed
+     * @return {object} - map of column name to column value
+     */
     getRow,
     getRowOrNull,
+
+    /**
+     * Get all returned rows.
+     *
+     * @method
+     * @param {string} query - SQL query with ? used as parameter placeholder
+     * @param {object[]} [params] - array of params if needed
+     * @return {object[]} - array of all rows, each row is a map of column name to column value
+     */
     getRows,
     iterateRows,
     getManyRows,
+
+    /**
+     * Get a map of first column mapping to second column.
+     *
+     * @method
+     * @param {string} query - SQL query with ? used as parameter placeholder
+     * @param {object[]} [params] - array of params if needed
+     * @return {object} - map of first column to second column
+     */
     getMap,
+
+    /**
+     * Get a first column in an array.
+     *
+     * @method
+     * @param {string} query - SQL query with ? used as parameter placeholder
+     * @param {object[]} [params] - array of params if needed
+     * @return {object[]} - array of first column of all returned rows
+     */
     getColumn,
+
+    /**
+     * Execute SQL
+     *
+     * @method
+     * @param {string} query - SQL query with ? used as parameter placeholder
+     * @param {object[]} [params] - array of params if needed
+     */
     execute,
     executeWithoutTransaction,
     executeMany,