From: Paul Donald Date: Sun, 15 Feb 2026 23:44:17 +0000 (+0100) Subject: luci-base: jsdoc fixes X-Git-Url: http://git.99rst.org/?a=commitdiff_plain;h=92381c3ca285c2303a59c74509fb4d6a422fece3;p=openwrt-luci.git luci-base: jsdoc fixes @name alone does not provide a linkable symbol. @member and @memberof do. Signed-off-by: Paul Donald --- diff --git a/modules/luci-base/htdocs/luci-static/resources/cbi.js b/modules/luci-base/htdocs/luci-static/resources/cbi.js index e694a105e4..ef3bd18b4d 100644 --- a/modules/luci-base/htdocs/luci-static/resources/cbi.js +++ b/modules/luci-base/htdocs/luci-static/resources/cbi.js @@ -11,18 +11,44 @@ http://www.apache.org/licenses/LICENSE-2.0 */ +/** + * CBI (Configuration Bindings Interface) helper utilities and DOM helpers. + * + * Provides initialization for CBI UI elements, dependency handling, + * validation wiring and miscellaneous helpers used by LuCI forms. Functions + * defined here are registered as global `window.*` symbols. + * @module LuCI.cbi + */ var cbi_d = []; var cbi_strings = { path: {}, label: {} }; +/** + * Read signed 8-bit integer from a byte array at the given offset. + * @param {Array} bytes - Byte array. + * @param {number} off - Offset into the array. + * @returns {number} Signed 8-bit value (returned as unsigned number). + */ function s8(bytes, off) { var n = bytes[off]; return (n > 0x7F) ? (n - 256) >>> 0 : n; } +/** + * Read unsigned 16-bit little-endian integer from a byte array at offset. + * @param {Array} bytes - Byte array. + * @param {number} off - Offset into the array. + * @returns {number} Unsigned 16-bit integer. + */ function u16(bytes, off) { return ((bytes[off + 1] << 8) + bytes[off]) >>> 0; } +/** + * Compute a stable 32-bit-ish string hash used for translation keys. + * Encodes UTF-8 surrogate pairs and mixes bytes into a hex hash string. + * @param {string|null} s - Input string. + * @returns {string|null} Hex hash string or null for empty input. + */ function sfh(s) { if (s === null || s.length === 0) return null; @@ -105,15 +131,35 @@ function sfh(s) { var plural_function = null; +/** + * Trim whitespace and normalise internal whitespace sequences to single spaces. + * @param {*} s - Value to convert to string and trim. + * @returns {string} Trimmed and normalised string. + */ function trimws(s) { return String(s).trim().replace(/[ \t\n]+/g, ' '); } +/** + * Lookup a translated string for the given message and optional context. + * Falls back to the source string when no translation found. + * @param {string} s - Source string. + * @param {string} [c] - Optional translation context. + * @returns {string} Translated string or original. + */ function _(s, c) { var k = (c != null ? trimws(c) + '\u0001' : '') + trimws(s); return (window.TR && TR[sfh(k)]) || s; } +/** + * Plural-aware translation lookup. + * @param {number} n - Quantity to evaluate plural form. + * @param {string} s - Singular string. + * @param {string} p - Plural string. + * @param {string} [c] - Optional context. + * @returns {string} Translated plural form or source string. + */ function N_(n, s, p, c) { if (plural_function == null && window.TR) plural_function = new Function('n', (TR['00000000'] || 'plural=(n != 1);') + 'return +plural'); @@ -125,6 +171,12 @@ function N_(n, s, p, c) { } +/** + * Register a dependency entry for a field. + * @param {HTMLElement|string} field - Field element or its id. + * @param {Object} dep - Dependency specification object. + * @param {number} index - Order index of the dependent node. + */ function cbi_d_add(field, dep, index) { var obj = (typeof(field) === 'string') ? document.getElementById(field) : field; if (obj) { @@ -149,6 +201,12 @@ function cbi_d_add(field, dep, index) { } } +/** + * Check whether an input/select identified by target matches the given reference value. + * @param {string} target - Element id or name to query. + * @param {string} ref - Reference value to compare with. + * @returns {boolean} True if the current value matches ref. + */ function cbi_d_checkvalue(target, ref) { var value = null, query = 'input[id="'+target+'"], input[name="'+target+'"], ' + @@ -162,6 +220,11 @@ function cbi_d_checkvalue(target, ref) { return (((value !== null) ? value : "") == ref); } +/** + * Evaluate a list of dependency descriptors and return whether any match. + * @param {Array} deps - Array of dependency objects to evaluate. + * @returns {boolean} True when dependencies indicate the element should be shown. + */ function cbi_d_check(deps) { var reverse; var def = false; @@ -186,6 +249,10 @@ function cbi_d_check(deps) { return def; } +/** + * Update DOM nodes based on registered dependencies, showing or hiding + * nodes and restoring their order when dependency state changes. + */ function cbi_d_update() { var state = false; for (var i=0; i