docs: add @internal tags to various pkgs

thi-ng · Nov 17, 2019 · b875897 · b875897
1 parent d306a72
commit b875897
Show file tree

Hide file tree

Showing 21 changed files with 71 additions and 13 deletions.
diff --git a/packages/api/src/api.ts b/packages/api/src/api.ts
@@ -4,6 +4,8 @@ export const DEFAULT_EPS = 1e-6;
 
 /**
  * Internal use only. **Do NOT use in user land code!**
+ *
+ * @internal
  */
 export const SEMAPHORE = Symbol();
 

diff --git a/packages/api/src/assert.ts b/packages/api/src/assert.ts
@@ -2,8 +2,10 @@ import { Fn0, NO_OP } from "./api/fn";
 
 /**
  * Takes a `test` result or predicate function without args and throws
- * error with given `msg` if test failed (i.e. is falsy). The function
- * is only enabled if `NODE_ENV != "production"` or if
+ * error with given `msg` if test failed (i.e. is falsy).
+ *
+ * @remarks
+ * The function is only enabled if `NODE_ENV != "production"` or if
  * `UMBRELLA_ASSERTS = 1`.
  */
 export const assert =

diff --git a/packages/color/src/internal/ensure-args.ts b/packages/color/src/internal/ensure-args.ts
@@ -1,3 +1,4 @@
+/** @internal */
 export const ensureArgs = (args: any[]) => {
     if (typeof args[0] === "number") {
         switch (args.length) {

diff --git a/packages/color/src/internal/ensure-hue.ts b/packages/color/src/internal/ensure-hue.ts
@@ -1 +1,2 @@
+/** @internal */
 export const ensureHue = (x: number) => ((x = x % 1), x < 0 ? x + 1 : x);
diff --git a/packages/hdom-canvas/src/draw/end-shape.ts b/packages/hdom-canvas/src/draw/end-shape.ts
@@ -1,5 +1,6 @@
 import { IObjectOf } from "@thi.ng/api";
 
+/** @internal */
 export const endShape = (
     ctx: CanvasRenderingContext2D,
     attribs: IObjectOf<any>

diff --git a/packages/hdom-canvas/src/impl.ts b/packages/hdom-canvas/src/impl.ts
@@ -83,6 +83,7 @@ export const canvas = {
     }
 };
 
+/** @internal */
 export const createTree = (
     _: Partial<HDOMOpts>,
     canvas: HTMLCanvasElement,
@@ -101,6 +102,7 @@ export const createTree = (
     walk(ctx!, tree, { attribs: {}, edits: [] });
 };
 
+/** @internal */
 export const normalizeTree = (opts: Partial<HDOMOpts>, tree: any): any => {
     if (tree == null) {
         return tree;
@@ -142,6 +144,7 @@ export const normalizeTree = (opts: Partial<HDOMOpts>, tree: any): any => {
     return tree;
 };
 
+/** @internal */
 export const diffTree = (
     opts: Partial<HDOMOpts>,
     parent: HTMLCanvasElement,

diff --git a/packages/hdom-canvas/src/state.ts b/packages/hdom-canvas/src/state.ts
@@ -57,6 +57,7 @@ const newState = (state: DrawState, restore = false) => ({
     restore
 });
 
+/** @internal */
 export const mergeState = (
     ctx: CanvasRenderingContext2D,
     state: DrawState,
@@ -82,6 +83,7 @@ export const mergeState = (
     return res;
 };
 
+/** @internal */
 export const restoreState = (
     ctx: CanvasRenderingContext2D,
     prev: DrawState,
@@ -100,6 +102,7 @@ export const restoreState = (
     }
 };
 
+/** @internal */
 export const registerGradient = (
     state: DrawState,
     id: string,

diff --git a/packages/hdom-canvas/src/walk.ts b/packages/hdom-canvas/src/walk.ts
@@ -13,6 +13,7 @@ import { rect } from "./draw/rect";
 import { text } from "./draw/text";
 import { mergeState, registerGradient, restoreState } from "./state";
 
+/** @internal */
 export const walk = (
     ctx: CanvasRenderingContext2D,
     shape: any[],

diff --git a/packages/hdom-components/src/utils/merge-attribs.ts b/packages/hdom-components/src/utils/merge-attribs.ts
@@ -5,12 +5,13 @@
  *
  * @param base - base attribs
  * @param xs - overrides
+ *
+ * @internal
  */
-export const mergeAttribs =
-    (base: any, xs: any) => {
-        if (!xs) return base;
-        const res = { ...base, ...xs };
-        base.class && xs.class && (res.class = base.class + " " + xs.class);
-        base.style && xs.style && (res.style = { ...base.style, ...xs.style });
-        return res;
-    };
+export const mergeAttribs = (base: any, xs: any) => {
+    if (!xs) return base;
+    const res = { ...base, ...xs };
+    base.class && xs.class && (res.class = base.class + " " + xs.class);
+    base.style && xs.style && (res.style = { ...base.style, ...xs.style });
+    return res;
+};
diff --git a/packages/hiccup-css/src/impl.ts b/packages/hiccup-css/src/impl.ts
@@ -29,8 +29,12 @@ const xfSel = comp<any, string, string>(
 );
 
 const withScope = (xf: Transducer<any, any>, scope: string) =>
-    comp(xf, map((x) => (isString(x) && x.indexOf(" .") == 0 ? x + scope : x)));
+    comp(
+        xf,
+        map((x) => (isString(x) && x.indexOf(" .") == 0 ? x + scope : x))
+    );
 
+/** @internal */
 export const expand = (
     acc: string[],
     parent: any[],
@@ -98,6 +102,7 @@ const formatRule = (parent: any[], sel: any[], curr: any, opts: CSSOpts) => {
     ].join("");
 };
 
+/** @internal */
 export const formatDecls = (rules: any, opts: CSSOpts) => {
     const f = opts.format;
     const prefixes = <Set<string>>(opts.autoprefix || EMPTY);
@@ -125,6 +130,7 @@ export const formatDecls = (rules: any, opts: CSSOpts) => {
     return acc.join(f.decls) + f.decls;
 };
 
+/** @internal */
 export const indent = (opts: CSSOpts, d = opts.depth) =>
     d > 1
         ? [...repeat(opts.format.indent, d)].join("")

diff --git a/packages/hiccup-css/src/quoted-functions.ts b/packages/hiccup-css/src/quoted-functions.ts
@@ -5,6 +5,7 @@ import { at_media } from "./media";
 import { at_namespace } from "./namespace";
 import { at_supports } from "./supports";
 
+/** @internal */
 export const QUOTED_FNS = {
     "@comment": comment,
     "@import": at_import,

diff --git a/packages/hiccup-svg/src/format.ts b/packages/hiccup-svg/src/format.ts
@@ -6,10 +6,13 @@ let PRECISION = 2;
 
 export const setPrecision = (n: number) => (PRECISION = n);
 
+/** @internal */
 export const ff = (x: number) => x.toFixed(PRECISION);
 
+/** @internal */
 export const fpoint = (p: Vec2Like) => ff(p[0]) + "," + ff(p[1]);
 
+/** @internal */
 export const fpoints = (pts: Vec2Like[], sep = " ") =>
     pts ? pts.map(fpoint).join(sep) : "";
 
@@ -41,6 +44,8 @@ export const fpoints = (pts: Vec2Like[], sep = " ") =>
  * null-ish.
  *
  * @param attribs -
+ *
+ * @internal
  */
 export const fattribs = (attribs: any) => {
     if (!attribs) return;
@@ -57,6 +62,8 @@ export const fattribs = (attribs: any) => {
  * {@link fattribs}
  *
  * @param attribs -
+ *
+ * @internal
  */
 const ftransforms = (attribs: any) => {
     let v: any;
@@ -110,6 +117,8 @@ const buildTransform = (attribs: any) => {
  * {@link fattribs}
  *
  * @param col -
+ *
+ * @internal
  */
 export const fcolor = (col: any) =>
     isString(col)

diff --git a/packages/hiccup/src/api.ts b/packages/hiccup/src/api.ts
@@ -2,6 +2,7 @@ export const SVG_NS = "http://www.w3.org/2000/svg";
 export const XLINK_NS = "http://www.w3.org/1999/xlink";
 export const XHTML_NS = "http://www.w3.org/1999/xhtml";
 
+/** @internal */
 export const PROC_TAGS: { [id: string]: string } = {
     "?xml": "?>\n",
     "!DOCTYPE": ">\n",
@@ -10,6 +11,7 @@ export const PROC_TAGS: { [id: string]: string } = {
     "!ATTLIST": ">\n"
 };
 
+/** @internal */
 export const ENTITIES: { [id: string]: string } = {
     "&": "&amp;",
     "<": "&lt;",
@@ -18,11 +20,15 @@ export const ENTITIES: { [id: string]: string } = {
     "'": "&apos;"
 };
 
+/** @internal */
 export const RE_TAG = /^([^\s\.#]+)(?:#([^\s\.#]+))?(?:\.([^\s#]+))?$/;
+/** @internal */
 export const RE_ENTITY = new RegExp(`[${Object.keys(ENTITIES).join("")}]`, "g");
 
+/** @internal */
 export const COMMENT = "__COMMENT__";
 
+/** @internal */
 export const NO_SPANS: {
     [id: string]: number;
 } = {
@@ -38,11 +44,13 @@ const tagMap = (
     [id: string]: boolean;
 } => tags.split(" ").reduce((acc: any, x) => ((acc[x] = true), acc), {});
 
+/** @internal */
 // tslint:disable-next-line
 export const SVG_TAGS = tagMap(
     "animate animateColor animateMotion animateTransform circle clipPath color-profile defs desc discard ellipse feBlend feColorMatrix feComponentTransfer feComposite feConvolveMatrix feDiffuseLighting feDisplacementMap feDistantLight feDropShadow feFlood feFuncA feFuncB feFuncG feFuncR feGaussianBlur feImage feMerge feMergeNode feMorphology feOffset fePointLight feSpecularLighting feSpotLight feTile feTurbulence filter font foreignObject g image line linearGradient marker mask metadata mpath path pattern polygon polyline radialGradient rect set stop style svg switch symbol text textPath title tref tspan use view"
 );
 
+/** @internal */
 // tslint:disable-next-line
 export const VOID_TAGS = tagMap(
     "area base br circle col command ellipse embed hr img input keygen line link meta param path polygon polyline rect source stop track use wbr ?xml"

diff --git a/packages/hiccup/src/deref.ts b/packages/hiccup/src/deref.ts
@@ -8,6 +8,8 @@ import { implementsFunction } from "@thi.ng/checks";
  *
  * @param ctx -
  * @param keys -
+ *
+ * @internal
  */
 export const derefContext = (ctx: any, keys: PropertyKey[] | undefined) => {
     if (ctx == null || !keys || !keys.length) return ctx;

diff --git a/packages/hiccup/src/serialize.ts b/packages/hiccup/src/serialize.ts
@@ -17,6 +17,8 @@ import { normalize } from "./normalize";
 /**
  * Recursively normalizes and serializes given tree as HTML/SVG/XML
  * string. Expands any embedded component functions with their results.
+ *
+ * @remarks
  * Each node of the input tree can have one of the following input
  * forms:
  *

diff --git a/packages/leb128/package.json b/packages/leb128/package.json
@@ -18,7 +18,7 @@
         "build:release": "yarn clean && yarn build:es6 && node ../../scripts/bundle-module all",
         "build:es6": "tsc --declaration",
         "build:test": "rimraf build && tsc -p test/tsconfig.json",
-        "build:binary": "echo \"export const BINARY = \\\"$(../../scripts/base64 opt.wasm)\\\";\" > src/binary.ts",
+        "build:binary": "echo \"/** @internal */\nexport const BINARY = \\\"$(../../scripts/base64 opt.wasm)\\\";\" > src/binary.ts",
         "test": "yarn build:test && mocha build/test/*.js",
         "cover": "yarn build:test && nyc mocha build/test/*.js && nyc report --reporter=lcov",
         "clean": "rimraf *.js *.d.ts .nyc_output build coverage doc lib",

diff --git a/packages/leb128/src/binary.ts b/packages/leb128/src/binary.ts
@@ -1,2 +1,3 @@
+/** @internal */
 export const BINARY =
     "AGFzbQEAAAABCgJgAXwBf2AAAXwDBQQAAQABBQMBAAIGFAN/AEGQiAQLfwBBiggLfwBBgAgLB38IBm1lbW9yeQIAC19faGVhcF9iYXNlAwAKX19kYXRhX2VuZAMBEmxlYjEyOF9lbmNvZGVfdV9qcwAAA2J1ZgMCEmxlYjEyOF9kZWNvZGVfdV9qcwABEmxlYjEyOF9lbmNvZGVfc19qcwACEmxlYjEyOF9kZWNvZGVfc19qcwADCoMEBHoCAn8BfgJAAkAgAEQAAAAAAADwQ2MgAEQAAAAAAAAAAGZxRQRADAELIACxIgNCgAFaDQELQYAIIAOnQf8AcToAAEEBDwsDQCABQYAIaiADpyICQf8AcSACQYABciADQgeIIgNQGzoAACABQQFqIQEgA0IAUg0ACyABC14CA38CfgJAA0AgAEEJSw0BIAFBAWohASAAQYAIaiwAACICQf8Aca0gBIYgA4QhAyAAQQFqIQAgBEIHfCEEIAJBf0wNAAtBgAggAToAACADug8LQYAIIAA6AAAgA7oLqwECBH8BfiAAmUQAAAAAAADgQ2MEfiAAsAVCgICAgICAgICAfwsiBUJAfUKAAVQEQEGACCAFQjmIp0HAAHEgBadBP3FyOgAAQQEPCwNAIAWnIgJBwABxIQMgAUGACGoCfwJAIAVCB4ciBUIAUQRAIANFDQELQQEhBCACQYB/ciADRSAFQn9Scg0BGgtBACEEIAJB/wBxCzoAACABQQFqIQEgBA0ACyABQf8BcQt6AgR/A34DQAJAIABBAWohASAFQgd8IQYgAEGACGotAAAiA0EYdEEYdSECIANB/wBxrSAFhiAEhCEEIABBCEsNACABIQAgBiEFIAJBAEgNAQsLQYAIIAE6AAAgBCAEQn8gBkI/g4aEIAJBwABxRSABQf8BcUEJS3IbuQs=";
diff --git a/packages/pixel/src/codegen.ts b/packages/pixel/src/codegen.ts
@@ -13,6 +13,7 @@ const compileRShift = (x: string, shift: number) => compileLShift(x, -shift);
 
 const hex = (x: number) => `0x${x.toString(16)}`;
 
+/** @internal */
 export const compileGrayFromABGR = (size: number) => {
     const shift = 8 - size;
     const mask = (1 << size) - 1;
@@ -24,6 +25,7 @@ export const compileGrayFromABGR = (size: number) => {
     );
 };
 
+/** @internal */
 export const compileGrayToABGR = (size: number) => {
     let body: string;
     if (size !== 8) {
@@ -39,6 +41,7 @@ export const compileGrayToABGR = (size: number) => {
     );
 };
 
+/** @internal */
 export const compileFromABGR = (chans: PackedChannel[]) =>
     <Fn<number, number>>new Function(
         "x",
@@ -52,6 +55,7 @@ export const compileFromABGR = (chans: PackedChannel[]) =>
             ") >>> 0;"
     );
 
+/** @internal */
 export const compileToABGR = (chans: PackedChannel[], hasAlpha: boolean) => {
     const body = chans
         .map((ch) => {

diff --git a/packages/pixel/src/utils.ts b/packages/pixel/src/utils.ts
@@ -8,13 +8,15 @@ import {
 import { clamp } from "@thi.ng/math";
 import { BlitOpts, PackedFormat } from "./api";
 
+/** @internal */
 export const ensureSize = (
     pixels: TypedArray,
     width: number,
     height: number,
     stride = 1
 ) => assert(pixels.length >= width * height * stride, "pixel buffer too small");
 
+/** @internal */
 export const ensureChannel = (fmt: PackedFormat, id: number) => {
     const chan = fmt.channels[id];
     assert(chan != null, `invalid channel ID: ${id}`);
@@ -25,6 +27,7 @@ export const luminanceABGR = (c: number) =>
     (((c >>> 16) & 0xff) * 29 + ((c >>> 8) & 0xff) * 150 + (c & 0xff) * 76) /
     255;
 
+/** @internal */
 export const clampRegion = (
     sx: number,
     sy: number,
@@ -40,6 +43,7 @@ export const clampRegion = (
     return [sx, sy, clamp(w, 0, maxw - sx), clamp(h, 0, maxh - sy), dx, dy];
 };
 
+/** @internal */
 export const prepRegions = (
     src: { width: number; height: number },
     dest: { width: number; height: number },
@@ -71,6 +75,7 @@ export const prepRegions = (
     return { sx, sy, dx, dy, rw, rh };
 };
 
+/** @internal */
 export const setChannelUni = (
     dbuf: UIntArray,
     src: number,
@@ -81,6 +86,7 @@ export const setChannelUni = (
     }
 };
 
+/** @internal */
 export const setChannelSame = (
     dbuf: UIntArray,
     sbuf: UIntArray,
@@ -92,6 +98,7 @@ export const setChannelSame = (
     }
 };
 
+/** @internal */
 export const setChannelConvert = (
     dbuf: UIntArray,
     sbuf: UIntArray,

diff --git a/packages/porter-duff/src/utils.ts b/packages/porter-duff/src/utils.ts
@@ -1,5 +1,6 @@
 import { Color, ReadonlyColor } from "./api";
 
+/** @internal */
 export const setC4 = (
     out: Color,
     a: number,
@@ -8,7 +9,9 @@ export const setC4 = (
     d: number
 ) => ((out[0] = a), (out[1] = b), (out[2] = c), (out[3] = d), out);
 
+/** @internal */
 export const setN4 = (out: Color, n: number) => setC4(out, n, n, n, n);
 
+/** @internal */
 export const setV4 = (out: Color, a: ReadonlyColor) =>
     setC4(out, a[0], a[1], a[2], a[3]);
diff --git a/packages/simd/package.json b/packages/simd/package.json
@@ -19,7 +19,7 @@
         "build:es6": "tsc --declaration",
         "build:test": "rimraf build && tsc -p test/tsconfig.json",
         "build:wasm": "asc assembly/index.ts -b simd.wasm -t simd.wat --validate --optimize --enable simd --runtime none --importMemory --memoryBase 0 && yarn build:binary",
-        "build:binary": "echo \"export const BINARY = \\\"$(../../scripts/base64 simd.wasm)\\\";\" > src/binary.ts",
+        "build:binary": "echo \"/** @internal */\nexport const BINARY = \\\"$(../../scripts/base64 simd.wasm)\\\";\" > src/binary.ts",
         "test": "yarn build:test && node --experimental-wasm-simd build/test/index.js",
         "cover": "yarn build:test && nyc node --experimental-wasm-simd build/test/*.js && nyc report --reporter=lcov",
         "clean": "rimraf *.js *.d.ts .nyc_output build coverage doc lib",
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,8 @@ export const DEFAULT_EPS = 1e-6; @@
     /**
      * Internal use only. **Do NOT use in user land code!**
+     *
+     * @internal
      */
     export const SEMAPHORE = Symbol();
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -1 +1,2 @@
		/** @internal */
		export const ensureHue = (x: number) => ((x = x % 1), x < 0 ? x + 1 : x);