diff --git a/ivette/src/dome/src/misc/plugins.js b/ivette/src/dome/src/misc/plugins.js index 5d468d4017a308f65f0dfad93f3ef2dcc6c17aea..87a08c0c836e960d70158825db1a98a685f2282c 100644 --- a/ivette/src/dome/src/misc/plugins.js +++ b/ivette/src/dome/src/misc/plugins.js @@ -34,7 +34,7 @@ export function install( name ) let config ; try { config = JSON.pargse(fs.readFileSync( pkg , 'UTF-8' )); } catch(err) { - console.error( `[Dome] reading '${pkg}':\n`, err ); + console.error( `[Dome] Reading '${pkg}':\n`, err ); throw `Plugin '${name}' has invalid 'package.json' file` ; } @@ -49,7 +49,7 @@ export function install( name ) let bundle ; try { bundle = fs.readFileSync( bundlejs , 'UTF-8' ); } catch(err) { - console.error( `[Dome] loading '${bundlejs}':\n`, err ); + console.error( `[Dome] Loading '${bundlejs}':\n`, err ); throw `Plugin '${name}' can not load its entry point` ; } @@ -63,7 +63,7 @@ export function install( name ) let module = { id, exports }; compiled( module, require, static_d ); } catch(err) { - console.error( `[Dome] running '${bundlejs}':\n`, err ); + console.error( `[Dome] Running '${bundlejs}':\n`, err ); throw `Plugin '${name}' can not install bundle` ; } register( id, exports ); // final exports diff --git a/ivette/src/dome/src/renderer/data/json.ts b/ivette/src/dome/src/renderer/data/json.ts index 2e28501d5998363a63138f7019b95c9ceb2dec17..4c1d36796e57d508ffef52d80abc2810e21e8744 100644 --- a/ivette/src/dome/src/renderer/data/json.ts +++ b/ivette/src/dome/src/renderer/data/json.ts @@ -5,7 +5,7 @@ /** Safe JSON utilities. @packageDocumentation - @package dome/data/json + @module dome/data/json */ import { DEVEL } from 'dome/system'; @@ -25,7 +25,7 @@ export function parse(text: string, noError = false): json { try { return JSON.parse(text); } catch (err) { - if (DEVEL) console.error('[Dome.json] invalid format:', err); + if (DEVEL) console.error('[Dome.json] Invalid format:', err); return undefined; } } else @@ -109,8 +109,7 @@ export const jString: Loose<string> = (js: json) => ( /** One of the enumerated _constants_ or `undefined`. The typechecker will prevent you from listing values that are not in - type `A`. However, it will not protected you - from missings constants in `A`. + type `A`. However, it will not protect you from missings constants in `A`. */ export function jEnum<A>(...values: ((string | number) & A)[]): Loose<A> { var m = new Map<string | number, A>(); @@ -127,12 +126,13 @@ export function jDefault<A>( fn: Loose<A>, defaultValue: A, ): Safe<A> { - return (js: json) => js === undefined ? defaultValue : (fn(js) ?? defaultValue); + return (js: json) => + js === undefined ? defaultValue : (fn(js) ?? defaultValue); } /** Force returning `undefined` or a default value for `undefined` JSON input. - Typically usefull to leverage an existing `Safe<A>` decoder. + Typically useful to leverage an existing `Safe<A>` decoder. */ export function jOption<A>(fn: Safe<A>, defaultValue?: A): Loose<A> { return (js: json) => (js === undefined ? defaultValue : fn(js)); @@ -140,7 +140,7 @@ export function jOption<A>(fn: Safe<A>, defaultValue?: A): Loose<A> { /** Force returning `undefined` or a default value for `undefined` _or_ `null` - JSON input. Typically usefull to leverage an existing `Safe<A>` decoder. + JSON input. Typically useful to leverage an existing `Safe<A>` decoder. */ export function jNull<A>(fn: Safe<A>, defaultValue?: A): Loose<A> { return (js: json) => (js === undefined || js === null ? defaultValue : fn(js)); @@ -188,7 +188,7 @@ export function jTry<A>(fn: Loose<A>, defaultValue?: A): Loose<A> { } /** - Converts maps to dictionnaries. + Converts maps to dictionaries. */ export function jMap<A>(fn: Loose<A>): Safe<Map<string, A>> { return (js: json) => { @@ -204,7 +204,7 @@ export function jMap<A>(fn: Loose<A>): Safe<Map<string, A>> { } /** - Converts dictionnaries to maps. + Converts dictionaries to maps. */ export function eMap<A>(fn: Encoder<A>): Encoder<Map<string, undefined | A>> { return m => { @@ -220,10 +220,10 @@ export function eMap<A>(fn: Encoder<A>): Encoder<Map<string, undefined | A>> { } /** - Apply the decoder on each item of a JSON array, or return `[]` otherwize. + Apply the decoder on each item of a JSON array, or return `[]` otherwise. Can be also applied on a _loose_ decoder, but you will get an array with possibly `undefined` elements. Use [[jList]] - to discard undefined elements, or use a true « safe » decoder. + to discard undefined elements, or use a true _safe_ decoder. */ export function jArray<A>(fn: Safe<A>): Safe<A[]> { return (js: json) => Array.isArray(js) ? js.map(fn) : []; @@ -231,7 +231,7 @@ export function jArray<A>(fn: Safe<A>): Safe<A[]> { /** Apply the loose decoder on each item of a JSON array, discarding - all `undefined` elements. To keep all, possibly undefined array entries, + all `undefined` elements. To keep the all possibly undefined array entries, use [[jArray]] instead. */ export function jList<A>(fn: Loose<A>): Safe<A[]> { @@ -382,7 +382,7 @@ export function eObject<A>(fp: EProps<A>): Encoder<A> { export type dict<A> = { [key: string]: A }; /** - Decode a JSON dictionary, dicarding all inconsistent entries. + Decode a JSON dictionary, discarding all inconsistent entries. If the JSON contains no valid entry, still returns `{}`. */ export function jDictionary<A>(fn: Loose<A>): Safe<dict<A>> { @@ -402,7 +402,7 @@ export function jDictionary<A>(fn: Loose<A>): Safe<dict<A>> { } /** - Encode a dictionary into JSON, dicarding all inconsistent entries. + Encode a dictionary into JSON, discarding all inconsistent entries. If the dictionary contains no valid entry, still returns `{}`. */ export function eDictionary<A>(fn: Encoder<A>): Encoder<dict<A>> { diff --git a/ivette/src/dome/src/renderer/data/states.ts b/ivette/src/dome/src/renderer/data/states.ts index 73c8d4e8475849b59babc80bb2ae8d025359fd18..b9e0de2a648e5d5fee1d0081ada3a9d4f58f7308 100644 --- a/ivette/src/dome/src/renderer/data/states.ts +++ b/ivette/src/dome/src/renderer/data/states.ts @@ -5,7 +5,7 @@ /** Typed States & Settings @packageDocumentation - @package dome/data/states + @module dome/data/states */ import React from 'react'; @@ -15,14 +15,16 @@ import * as Dome from 'dome'; import * as JSON from './json'; export type NonFunction = - undefined | null | boolean | number | string | object | any[] | bigint | symbol; + undefined | null | boolean | number | string + | object | any[] | bigint | symbol; /** State updater. New value or updating function applied to the current, lastly updated value. Use `null` to restore default value. */ export type updateAction<A extends NonFunction> = null | A | ((current: A) => A); -/** The type of updater callbacks. Typically used for `[A,setState<A>]` hooks. */ +/** The type of updater callbacks. Typically used for `[A, setState<A>]` + hooks. */ export type setState<A extends NonFunction> = (action: updateAction<A>) => void; /** Base state interface. */ @@ -127,18 +129,19 @@ export class StateOpt<A extends NonFunction> extends StateDef<undefined | A> { When several components share the same setting `dataKey` the behavior will be different depending on the situation: - for Window Settings, each component in each window retains its own - setting value, although the last modified value from _any_ of them will be saved - and used for any further initial value; + setting value, although the last modified value from _any_ of them will be + saved and used for any further initial value; - for Global Settings, all components synchronize to the last modified value from any component of any window. Type safety is ensured by safe JSON encoders and decoders, however, they might fail at runtime, causing settings value to be initialized to their - fallback and not to be saved or synchronized. This is not harmfull but annoying. + fallback and not to be saved nor synchronized. + This is not harmful but annoying. To mitigate this effect, each instance of a Settings class has its own, private, unique symbol that we call its « role ». A given `dataKey` - shall always be used with the same « role » otherwized it is discarded, + shall always be used with the same « role » otherwise it is discarded, and an error message is logged when in DEVEL mode. */ abstract class Settings<A> { @@ -153,11 +156,12 @@ abstract class Settings<A> { Encoders shall be protected against exception. Use [[JSON.jTry]] and [[JSON.jCatch]] in case of uncertainty. Decoders are automatically protected internally to the Settings class. - @param role - Debugging name of instance roles (each instance has its unique role, though) - @param decoder - JSON decoder for the setting values - @param encoder - JSON encoder for the setting values - @param fallback - - If provided, used to automatically protect your encoders against exceptions. + @param role Debugging name of instance roles (each instance has its unique + role, though) + @param decoder JSON decoder for the setting values + @param encoder JSON encoder for the setting values + @param fallback If provided, used to automatically protect your encoders + against exceptions. */ constructor( role: string, @@ -185,7 +189,7 @@ abstract class Settings<A> { } else { if (rk !== rq) { if (DEVEL) console.error( - `[Dome.settings] key ${dataKey} used with incompatible roles`, rk, rq, + `[Dome.settings] Key ${dataKey} used with incompatible roles`, rk, rq, ); return undefined; } @@ -209,13 +213,13 @@ abstract class Settings<A> { } /** Push the new setting value for the provided data key. - You only use validated keys otherwise further loads + You shall only use validated keys otherwise further loads might fail and fallback to defaults. */ saveValue(dataKey: string, value: A) { try { this.saveData(dataKey, this.encoder(value)); } catch (err) { if (DEVEL) console.error( - '[Dome.settings] error while encoding value', + '[Dome.settings] Error while encoding value', dataKey, value, err, ); } @@ -228,8 +232,8 @@ abstract class Settings<A> { You may share `dataKey` between components, or change it dynamically. However, a given data key shall always be used for the same Setting instance. See [[Settings]] documentation for details. - @param S - the instance settings to be used - @param dataKey - identifies which value in the settings to be used + @param S The instance settings to be used. + @param dataKey Identifies which value in the settings to be used. */ export function useSettings<A>( S: Settings<A>, diff --git a/ivette/src/dome/src/renderer/table/views.tsx b/ivette/src/dome/src/renderer/table/views.tsx index 953cdbdf5901e39f3b9ae3eff6de5a7affa1f1b8..b485a7e8a5ccb7d062c7bd6e61eac70aeba48002 100644 --- a/ivette/src/dome/src/renderer/table/views.tsx +++ b/ivette/src/dome/src/renderer/table/views.tsx @@ -212,7 +212,7 @@ function makeDataGetter( if (rowData !== undefined) return getter(rowData, dataKey); } catch (err) { console.error( - '[Dome.table] custom getter error', + '[Dome.table] Custom getter error', 'rowData:', rowData, 'dataKey:', dataKey, err, @@ -240,7 +240,7 @@ function makeDataRenderer( return contents; } catch (err) { console.error( - '[Dome.table] custom renderer error', + '[Dome.table] Custom renderer error', 'dataKey:', props.dataKey, 'cellData:', cellData, err, diff --git a/ivette/src/dome/src/renderer/text/buffers.js b/ivette/src/dome/src/renderer/text/buffers.js index 2546e8f5b7cc81d1a159c4a2d218c811fc028625..444970d2c104736ea9ac09970ea030638a836dfa 100644 --- a/ivette/src/dome/src/renderer/text/buffers.js +++ b/ivette/src/dome/src/renderer/text/buffers.js @@ -564,7 +564,7 @@ is blocked. } else if (typeof text === 'string') { this.append(text); } else if (text !== null) { - console.error('[Dome.buffers] unexpected text',text); + console.error('[Dome.buffers] Unexpected text', text); } }