From c52410ab4200dbad1b24e9cde2dce717810d04d0 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Fri, 10 Sep 2021 17:00:17 +0200
Subject: [PATCH] version-bridge: document versioned context helpers

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
---
 .../src/lib/VersionedContext.ts               | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/version-bridge/src/lib/VersionedContext.ts b/packages/version-bridge/src/lib/VersionedContext.ts
index 3cce599d11..62aed0d9ed 100644
--- a/packages/version-bridge/src/lib/VersionedContext.ts
+++ b/packages/version-bridge/src/lib/VersionedContext.ts
@@ -18,6 +18,20 @@ import { createContext, useContext, Context } from 'react';
 import { getGlobalSingleton } from './globalObject';
 import { createVersionedValueMap, VersionedValue } from './VersionedValue';
 
+/**
+ * A hook that simplifies the consumption of a versioned contexts that's
+ * stored inside a global singleton.
+ *
+ * @example
+ *
+ * ```ts
+ * const versionedHolder = useVersionedContext<{ 1: string }>('my-context');
+ *
+ * const myValue = versionedHolder.atVersion(1);
+ *
+ * // ...
+ * ````
+ */
 export function useVersionedContext<
   Versions extends { [version in number]: any },
 >(key: string): VersionedValue<Versions> {
@@ -30,6 +44,26 @@ export function useVersionedContext<
   return versionedValue;
 }
 
+/**
+ * Creates a helper for writing tests towards multiple different
+ * combinations of versions provided from a context.
+ *
+ * @example
+ *
+ * ```ts
+ * const context = createVersionedContextForTesting('my-context');
+ *
+ * afterEach(() => {
+ *   context.reset();
+ * });
+ *
+ * it('should work when provided with version 1', () => {
+ *   context.set({1: 'value-for-version-1'})
+ *
+ *   // ...
+ * })
+ * ```
+ */
 export function createVersionedContextForTesting(key: string) {
   return {
     set(versions: { [version in number]: unknown }) {