Formatting changes for api docs

theatre/core/src/propTypes/index.ts

@@ -45,6 +45,7 @@ const validateCommonOpts = (
 /**
  * A compound prop type (basically a JS object).
  *
+ * @example
  * Usage:
  * ```ts
  * // shorthand
@@ -86,6 +87,7 @@ export const compound = <Props extends IShorthandCompoundProps>(
 /**
  * A number prop type.
  *
+ * @example
  * Usage
  * ```ts
  * // shorthand:
@@ -206,6 +208,7 @@ export const number = (
 /**
  * A boolean prop type
  *
+ * @example
  * Usage:
  * ```ts
  * // shorthand:
@@ -248,6 +251,7 @@ export const boolean = (
 /**
  * A string prop type
  *
+ * @example
  * Usage:
  * ```ts
  * // shorthand:

theatre/core/src/sequences/TheatreSequence.ts

@@ -31,6 +31,7 @@ export interface ISequence {
    *
    * @returns A promise that resolves when the playback is finished, or rejects if interruped
    *
+   * @example
    * Usage:
    * ```ts
    * // plays the sequence from the current position to sequence.length
@@ -95,6 +96,7 @@ export interface ISequence {
    *
    * Learn more [here](https://docs.theatrejs.com/in-depth/#sequence-attachaudio).
    *
+   * @example
    * Usage:
    * ```ts
    * // Loads and decodes audio from the URL and then attaches it to the sequence
@@ -116,6 +118,7 @@ export interface ISequence {
    * optimal user experience. It is better to provide a button or some other UI element
    * to communicate to the user that they have to initiate the animation.
    *
+   * @example
    * Example:
    * ```ts
    * // html: <button id="#start">start</button>
@@ -154,6 +157,7 @@ export interface ISequence {
      * This is an intermediate GainNode that Theatre feeds its audio to. It is by default
      * connected to destinationNode, but you can disconnect the gainNode and feed it to your own graph.
      *
+     * @example
      * For example:
      * ```ts
      * const {gainNode, audioContext} = await sequence.attachAudio({source: '/audio.mp3'})

theatre/core/src/sheetObjects/TheatreSheetObject.ts

@@ -26,6 +26,7 @@ export interface ISheetObject<Props extends IShorthandCompoundProps = {}> {
   /**
    * The current values of the props.
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("obj", {x: 0})
@@ -61,6 +62,7 @@ export interface ISheetObject<Props extends IShorthandCompoundProps = {}> {
    *
    * @returns an Unsubscribe function
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("Box", {position: {x: 0, y: 0}})
@@ -81,7 +83,7 @@ export interface ISheetObject<Props extends IShorthandCompoundProps = {}> {
    * values defined in the prop types, but would itself be overridden if the user
    * overrides it in the UI with a static or animated value.
    *
-   *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("obj", {position: {x: 0, y: 0}})

theatre/core/src/sheets/TheatreSheet.ts

@@ -45,6 +45,7 @@ export interface ISheet {
    *
    * @returns An Object
    *
+   * @example
    * Usage:
    * ```ts
    * // Create an object named "a unique key" with no props

theatre/shared/src/utils/addresses.ts

@@ -14,6 +14,7 @@ export interface ProjectAddress {
 /**
  * Represents the address to a specific instance of a Sheet
  *
+ * @example
  * ```ts
  * const sheet = project.sheet('a sheet', 'some instance id')
  * sheet.address.sheetId === 'a sheet'
@@ -44,6 +45,7 @@ export interface SheetObjectAddress extends SheetAddress {
   /**
    * The key of the object.
    *
+   * @example
    * ```ts
    * const obj = sheet.object('foo', {})
    * obj.address.objectKey === 'foo'

theatre/studio/src/Scrub.ts

@@ -31,6 +31,10 @@ export interface IScrubApi {
    * Set the value of a prop by its pointer. If the prop is sequenced, the value
    * will be a keyframe at the current sequence position.
    *
+   * @param pointer - A Pointer, like object.props
+   * @param value - The value to override the existing value. This is treated as a deep partial value.
+   *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("box", {x: 0, y: 0})
@@ -45,8 +49,6 @@ export interface IScrubApi {
    *   set(obj.props.z, 10)
    * })
    * ```
-   * @param pointer - A Pointer, like object.props
-   * @param value - The value to override the existing value. This is treated as a deep partial value.
    */
   set<T>(pointer: Pointer<T>, value: T): void
 }
@@ -67,6 +69,7 @@ export interface IScrub {
    * Note that running `scrub.capture()` multiple times means all the older
    * calls of `scrub.capture()` will be reset.
    *
+   * @example
    * Usage:
    * ```ts
    * scrub.capture(({set}) => {

theatre/studio/src/TheatreStudio.ts

@@ -22,6 +22,7 @@ export interface ITransactionAPI {
    * Set the value of a prop by its pointer. If the prop is sequenced, the value
    * will be a keyframe at the current sequence position.
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("box", {x: 0, y: 0})
@@ -42,6 +43,7 @@ export interface ITransactionAPI {
   /**
    * Unsets the value of a prop by its pointer.
    *
+   * @example
    * Usage:
    * ```ts
    * const obj = sheet.object("box", {x: 0, y: 0})
@@ -91,15 +93,23 @@ export interface IExtension {
   id: string
   /**
    * Set this if you'd like to add a component to the global toolbar (on the top)
+   *
+   * @example
+   * TODO
    */
   globalToolbar?: {
     /**
      * A basic react component.
+     *
+     * @example
+     * TODO
      */
     component: React.ComponentType<{}>
   }
   /**
    * Introduces new pane types.
+   * @example
+   * TODO
    */
   panes?: Array<PaneClassDefinition>
 }
@@ -109,9 +119,42 @@ export type PaneInstance<ClassName extends string> = {
   instanceId: string
   definition: PaneClassDefinition
 }
+
+export interface IStudioUI {
+  /**
+   * Temporarily hides the studio
+   */
+  hide(): void
+  /**
+   * Whether the studio is currently visible or hidden
+   */
+  readonly isHidden: boolean
+  /**
+   * Makes the studio visible again.
+   */
+  restore(): void
+}
+
+export interface _StudioInitializeOpts {
+  /**
+   * The local storage key to use to persist the state.
+   *
+   * Default: "theatrejs:0.4"
+   */
+  persistenceKey?: string
+  /**
+   * Whether to persist the changes in the browser's temporary storage.
+   * It is useful to set this to false in the test environment or when debugging things.
+   *
+   * Default: true
+   */
+  usePersistentStorage?: boolean
+}
+
 /**
  * This is the public api of Theatre's studio. It is exposed through:
  *
+ * @example
  * Basic usage:
  * ```ts
  * import studio from '@theatre/studio'
@@ -119,6 +162,7 @@ export type PaneInstance<ClassName extends string> = {
  * studio.initialize()
  * ```
  *
+ * @example
  * Usage with **tree-shaking**:
  * ```ts
  * import studio from '@theatre/studio'
@@ -129,40 +173,13 @@ export type PaneInstance<ClassName extends string> = {
  * ```
  */
 export interface IStudio {
-  readonly ui: {
-    /**
-     * Temporarily hides the studio
-     */
-    hide(): void
-    /**
-     * Whether the studio is currently visible or hidden
-     */
-    readonly isHidden: boolean
-    /**
-     * Makes the studio visible again.
-     */
-    restore(): void
-  }
+  readonly ui: IStudioUI
 
   /**
    * Initializes the studio. Call it once in your index.js/index.ts module.
    * It silently ignores subsequent calls.
    */
-  initialize(opts?: {
-    /**
-     * The local storage key to use to persist the state.
-     *
-     * Default: "theatrejs:0.4"
-     */
-    persistenceKey?: string
-    /**
-     * Whether to persist the changes in the browser's temporary storage.
-     * It is useful to set this to false in the test environment or when debugging things.
-     *
-     * Default: true
-     */
-    usePersistentStorage?: boolean
-  }): void
+  initialize(opts?: _StudioInitializeOpts): void
 
   /**
    * Runs an undo-able transaction. Creates a single undo level for all
@@ -170,6 +187,7 @@ export interface IStudio {
    *
    * Will roll back if an error is thrown.
    *
+   * @example
    * Usage:
    * ```ts
    * studio.transaction(({set, unset}) => {
@@ -184,6 +202,7 @@ export interface IStudio {
    * Creates a scrub, which is just like a transaction, except you
    * can run it multiple times without creating extra undo levels.
    *
+   * @example
    * Usage:
    * ```ts
    * const scrub = studio.scrub()
@@ -214,6 +233,7 @@ export interface IStudio {
    *
    * @param threshhold - How long to wait before committing the scrub
    *
+   * @example
    * Usage:
    * ```ts
    * // Will create a new undo-level after 2 seconds have passed
@@ -246,6 +266,7 @@ export interface IStudio {
   /**
    * Sets the current selection.
    *
+   * @example
    * Usage:
    * ```ts
    * const sheet1: ISheet = ...
@@ -268,7 +289,8 @@ export interface IStudio {
   /**
    * The current selection, consisting of Sheets and Sheet Objects
    *
-   * Example:
+   * @example
+   * Usage:
    * ```ts
    * console.log(studio.selection) // => [ISheetObject, ISheet]
    * ```
@@ -309,6 +331,7 @@ export interface IStudio {
    *
    * @param projectId - same projectId as in `core.getProject(projectId)`
    *
+   * @example
    * Usage:
    * ```ts
    * const projectId = "project"

theatre/studio/src/index.ts

@@ -67,4 +67,11 @@ export {default as ToolbarSwitchSelect} from './uiComponents/toolbar/ToolbarSwit
 export {default as ToolbarIconButton} from './uiComponents/toolbar/ToolbarIconButton'
 export {default as ToolbarDropdownSelect} from './uiComponents/toolbar/ToolbarDropdownSelect'
 export type {IScrub} from '@theatre/studio/Scrub'
-export type {IStudio, IExtension} from '@theatre/studio/TheatreStudio'
+export type {
+  IStudio,
+  IExtension,
+  PaneInstance,
+  PaneClassDefinition,
+  IStudioUI,
+  _StudioInitializeOpts,
+} from '@theatre/studio/TheatreStudio'

theatre/studio/src/utils/useRefAndState.ts

@@ -4,6 +4,7 @@ import {useMemo, useState} from 'react'
 /**
  * Combines useRef() and useState().
  *
+ * @example
  * Usage:
  * ```ts
  * const [ref, val] = useRefAndState<HTMLDivElement | null>(null)