docs(color): fix #387 document fn behaviors if out arg is null

thi-ng · Mar 1, 2023 · cda14bf · cda14bf
1 parent bf9fe39
commit cda14bf
Show file tree

Hide file tree

Showing 10 changed files with 126 additions and 2 deletions.
diff --git a/packages/color/src/alpha.ts b/packages/color/src/alpha.ts
@@ -4,6 +4,14 @@ import type { Color, ReadonlyColor } from "./api.js";
 export const alpha = (src: ReadonlyColor) =>
 	src[3] !== undefined ? src[3] : 1;
 
+/**
+ * Creates version of `src` color with modified `alpha` and writes result into
+ * `out` (or if null, back into `src`).
+ *
+ * @param out
+ * @param src
+ * @param alpha
+ */
 export const setAlpha = (
 	out: Color | null,
 	src: ReadonlyColor,

diff --git a/packages/color/src/analog.ts b/packages/color/src/analog.ts
@@ -56,6 +56,10 @@ const analogNUU = defAnalog(analogN, analogU, analogU);
  * provided
  * [`IRandom`](https://docs.thi.ng/umbrella/random/interfaces/IRandom.html)
  * PRNG.
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  */
 export const analog = defmulti<
 	Color | null,

diff --git a/packages/color/src/api.ts b/packages/color/src/api.ts
@@ -19,6 +19,9 @@ export type MaybeColor =
 	| string
 	| number;
 
+/**
+ * Color manipulation function. If `out` is null, the `src` will be mutated.
+ */
 export type ColorOp = (out: Color | null, src: ReadonlyColor) => Color;
 
 export type ColorMode =

diff --git a/packages/color/src/clamp.ts b/packages/color/src/clamp.ts
@@ -9,6 +9,9 @@ import { __ensureAlpha } from "./internal/ensure.js";
  * to ensure alpha channel is defined (if missing sets it to `alpha`,
  * default: 1).
  *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  * @param out - result
  * @param src - source color
  * @param alpha - alpha value
@@ -26,6 +29,9 @@ export const clamp = (out: Color | null, src: ReadonlyColor, alpha = 1) =>
  * Similar to {@link clamp}, but calls `ensureHue` to fold (instead of
  * clamping) the hue into [0,1] interval.
  *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  * @param out - result
  * @param src - source color
  * @param alpha - alpha value

diff --git a/packages/color/src/convert.ts b/packages/color/src/convert.ts
@@ -38,6 +38,15 @@ export const defConversions = (
 	CONVERSIONS[mode] = { ...CONVERSIONS[mode], ...(<Conversions>spec) };
 };
 
+/**
+ * Converts a (raw, untyped) color from one mode to another and writes result
+ * into `out` (or if null, back into `src`).
+ *
+ * @param res
+ * @param src
+ * @param destMode
+ * @param srcMode
+ */
 export const convert = <T extends Color>(
 	res: T | null,
 	src: ReadonlyColor,

diff --git a/packages/color/src/invert.ts b/packages/color/src/invert.ts
@@ -14,6 +14,8 @@ import { __ensureAlpha } from "./internal/ensure.js";
  * Inverts the RGB channels of an RGBA color.
  *
  * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
  * Also see {@link TypedColor.invert}.
  *
  * @param out - result
@@ -34,6 +36,13 @@ export const invertRgb: ColorOp = (out, src) => {
  */
 export const invertInt = (src: number) => src ^ 0xffffff;
 
+/**
+ * Inverts given color and writes result into `out` (or if null, mutates `src`
+ * in place).
+ *
+ * @param out
+ * @param src
+ */
 export const invert = defmulti<Color | null, TypedColor<any>, Color>(
 	__dispatch1,
 	{

diff --git a/packages/color/src/lighten.ts b/packages/color/src/lighten.ts
@@ -15,6 +15,9 @@ const $ =
  * Adjust the "lightness" (luma, brightness etc.) channel of given `src` color
  * and `delta` offset. Writes result into `out` (or if null, back into `src`).
  *
+ * @remarks
+ * If `offset` is negative, then color will be darkened.
+ *
  * @param out -
  * @param src -
  * @param delta -

diff --git a/packages/color/src/mix.ts b/packages/color/src/mix.ts
@@ -75,10 +75,12 @@ export const mixNNNN: ColorMixFn = mixN4;
 
 /**
  * Channelwise and {@link ColorMode}-aware interpolation between colors `a` and
- * `b` using `t` [0..1] as blend factor. `a` and `b` need to be of same color
+ * `b` using `t` [0..1] as blend factor. `a` and `b` MUST be of same color
  * type.
  *
  * @remarks
+ * If `out` is null, the resulting color will be written back into `a`.
+ *
  * Any hue channel will always be interpolated using the smallest angle
  * difference (using {@link mixH}).
  *

diff --git a/packages/color/src/rotate.ts b/packages/color/src/rotate.ts
@@ -5,6 +5,30 @@ import type { Color, TypedColor } from "./api.js";
 import { __dispatch1 } from "./internal/dispatch.js";
 import { __ensureAlpha } from "./internal/ensure.js";
 
+/**
+ * Color rotation. Rotates hue by given `theta` and writes result color into
+ * `out`.
+ *
+ * @remarks
+ * If `out` is null, the resulting will be written back into `src`.
+ *
+ * As with all hue-based color modes in this package, the hue is stored
+ * normalized (in [0..1] interval) and NOT as degrees. The same goes for the
+ * rotation angle `theta`.
+ *
+ * Only supported for hue based color modes:
+ *
+ * - hcy
+ * - hsi
+ * - hsl
+ * - hsv
+ * - lch
+ * - oklch
+ *
+ * @param out
+ * @param src
+ * @param theta
+ */
 export const rotate = defmulti<Color | null, TypedColor<any>, number, Color>(
 	__dispatch1,
 	{ hsv: "hsl", hsi: "hsl", hcy: "hsl" },
@@ -28,5 +52,14 @@ export const rotate = defmulti<Color | null, TypedColor<any>, number, Color>(
 	}
 );
 
+/**
+ * Syntax sugar for {@link rotate} with 180 degree rotation.
+ *
+ * @remarks
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ */
 export const complementary = (out: Color | null, src: TypedColor<any>) =>
 	rotate(out, src, 0.5);
diff --git a/packages/color/src/tint.ts b/packages/color/src/tint.ts
@@ -6,6 +6,29 @@ import type { Color, TypedColor } from "./api.js";
 import { __dispatch1 } from "./internal/dispatch.js";
 import { __ensureAlpha } from "./internal/ensure.js";
 
+/**
+ * Creates a tinted version of given `src` color and writes result into `out`.
+ * The color is interpolated towards given `target` grayscale level (default: 1
+ * aka white).
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * Only supported for the following color modes:
+ *
+ * - hcy
+ * - hsi
+ * - hsv
+ * - lch
+ * - oklch
+ *
+ * @param out
+ * @param src
+ * @param amount
+ * @param target
+ */
 export const tint: MultiFn3O<
 	Color | null,
 	TypedColor<any>,
@@ -14,7 +37,7 @@ export const tint: MultiFn3O<
 	Color
 > = defmulti<Color | null, TypedColor<any>, number, number | undefined, Color>(
 	__dispatch1,
-	{ hcy: "hsv", hsi: "hsv", hsl: "hsv" },
+	{ hcy: "hsv", hsi: "hsv", hsl: "hsv", oklch: "lch" },
 	{
 		hsv: (out, src, n, l = 1) =>
 			setC4(
@@ -35,8 +58,32 @@ export const tint: MultiFn3O<
 	}
 );
 
+/**
+ * Version of {@link tint} with medium gray as target.
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ * @param n
+ */
 export const tone = (out: Color | null, src: TypedColor<any>, n: number) =>
 	tint(out, src, n, 0.5);
 
+/**
+ * Version of {@link tint} with black as target.
+ *
+ * @remarks
+ * Reference: https://www.handprint.com/HP/WCL/color3.html#stt
+ *
+ * If `out` is null, the resulting color will be written back into `src`.
+ *
+ * @param out
+ * @param src
+ * @param n
+ */
 export const shade = (out: Color | null, src: TypedColor<any>, n: number) =>
 	tint(out, src, n, 0);