From f3dfb7cedb03dea0fa7c629e32eaa31ba20c10b3 Mon Sep 17 00:00:00 2001
From: Aria Minaei <aria.minaei@gmail.com>
Date: Sun, 10 Apr 2022 20:03:49 +0200
Subject: [PATCH] Add comments to `Interpolator<T>`

https://github.com/theatre-js/theatre/pull/118#discussion_r846632746
---
 theatre/core/src/propTypes/index.ts | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/theatre/core/src/propTypes/index.ts b/theatre/core/src/propTypes/index.ts
index 452ac57..dd59f22 100644
--- a/theatre/core/src/propTypes/index.ts
+++ b/theatre/core/src/propTypes/index.ts
@@ -556,6 +556,24 @@ export function stringLiteral<
 }
 
 export type Sanitizer<T> = (value: unknown) => T | undefined
+
+/**
+ * A linear interpolator for a certain value type.
+ *
+ * @param left - the value to interpolate from (beginning)
+ * @param right - the value to interpolate to (end)
+ * @param progression - the amount of progression. Starts at 0 and ends at 1. But could overshoot in either direction
+ *
+ * @example
+ * ```ts
+ * const numberInterpolator: Interpolator<number> = (left, right, progression) => left + progression * (right - left)
+ *
+ * numberInterpolator(-50, 50, 0.5) === 0
+ * numberInterpolator(-50, 50, 0) === -50
+ * numberInterpolator(-50, 50, 1) === 50
+ * numberInterpolator(-50, 50, 2) === 150 // overshoot
+ * ```
+ */
 export type Interpolator<T> = (left: T, right: T, progression: number) => T
 
 export interface IBasePropType<