diff --git a/packages/dataverse/src/derivations/iterateOver.test.ts b/packages/dataverse/src/derivations/iterateOver.test.ts index 0de7036..39d6f6d 100644 --- a/packages/dataverse/src/derivations/iterateOver.test.ts +++ b/packages/dataverse/src/derivations/iterateOver.test.ts @@ -1,4 +1,5 @@ /** + * // eslint-disable-next-line * @jest-environment jsdom */ import Atom from '../Atom' diff --git a/packages/dataverse/src/derivations/prism/prism.test.ts b/packages/dataverse/src/derivations/prism/prism.test.ts index b3dd457..85fb416 100644 --- a/packages/dataverse/src/derivations/prism/prism.test.ts +++ b/packages/dataverse/src/derivations/prism/prism.test.ts @@ -1,4 +1,5 @@ /** + // eslint-disable-next-line * @jest-environment jsdom */ import Atom, {val} from '../../Atom' diff --git a/packages/dataverse/src/integration.test.ts b/packages/dataverse/src/integration.test.ts index 8f3e2d2..5ee86ef 100644 --- a/packages/dataverse/src/integration.test.ts +++ b/packages/dataverse/src/integration.test.ts @@ -1,4 +1,5 @@ /** + // eslint-disable-next-line * @jest-environment jsdom */ import Atom, {val} from './Atom' diff --git a/packages/r3f/src/components/RefreshSnapshot.tsx b/packages/r3f/src/components/RefreshSnapshot.tsx index a091761..2819313 100644 --- a/packages/r3f/src/components/RefreshSnapshot.tsx +++ b/packages/r3f/src/components/RefreshSnapshot.tsx @@ -5,9 +5,9 @@ import useRefreshSnapshot from './useRefreshSnapshot' * Putting this element in a suspense tree makes sure the snapshot editor * gets refreshed once the tree renders. * - * Alternatively you can use - * @link useRefreshSnapshot() + * Alternatively you can use {@link useRefreshSnapshot} * + * @example * Usage * ```jsx * diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts index d23384f..c735e52 100644 --- a/packages/react/src/index.ts +++ b/packages/react/src/index.ts @@ -148,7 +148,7 @@ function queueIfNeeded() { * @remarks * It looks like this new implementation of useDerivation() manages to: * 1. Not over-calculate the derivations - * 2. Render derivation in ancestor -> descendent order + * 2. Render derivation in ancestor -\> descendent order * 3. Not set off React's concurrent mode alarms * * It works like an implementation of Dataverse's Ticker, except that it runs diff --git a/theatre/core/src/coreTicker.ts b/theatre/core/src/coreTicker.ts index afeb05c..9f8b252 100644 --- a/theatre/core/src/coreTicker.ts +++ b/theatre/core/src/coreTicker.ts @@ -5,7 +5,8 @@ const coreTicker = new Ticker() export default coreTicker /** - * @todo users should also be able to define their own ticker. + * @remarks + * TODO users should also be able to define their own ticker. */ const onAnimationFrame = (t: number) => { coreTicker.tick(t) diff --git a/theatre/core/src/index.ts b/theatre/core/src/index.ts index e2581bd..4cedf4b 100644 --- a/theatre/core/src/index.ts +++ b/theatre/core/src/index.ts @@ -1,8 +1,6 @@ /** * Theatre comes in two packages: `@theatre/core` (the library) and * `@theatre/studio` (the editor). This package is the core library. - * - * @module \@theatre/core */ export * from './coreExports' export type { diff --git a/theatre/core/src/projects/initialiseProjectState.ts b/theatre/core/src/projects/initialiseProjectState.ts index e36dd61..71fa3a4 100644 --- a/theatre/core/src/projects/initialiseProjectState.ts +++ b/theatre/core/src/projects/initialiseProjectState.ts @@ -6,8 +6,9 @@ import type {OnDiskState} from './store/storeTypes' import globals from '@theatre/shared/globals' /** - * @todo this could be turned into a simple derivation, like: - * editor.isReady: IDerivation<{isReady: true} | {isReady: false, reason: 'conflictBetweenDiskStateAndBrowserState'}> + * @remarks + * TODO this could be turned into a simple derivation, like: + * `editor.isReady: IDerivation<{isReady: true} | {isReady: false, reason: 'conflictBetweenDiskStateAndBrowserState'}>` */ export default async function initialiseProjectState( studio: Studio, diff --git a/theatre/core/src/propTypes/index.ts b/theatre/core/src/propTypes/index.ts index 199251e..3078e73 100644 --- a/theatre/core/src/propTypes/index.ts +++ b/theatre/core/src/propTypes/index.ts @@ -291,6 +291,7 @@ export const string = ( /** * A stringLiteral prop type, useful for building menus or radio buttons. * + * @example * Usage: * ```ts * // Basic usage @@ -304,16 +305,23 @@ export const string = ( * }, {as: "switch", label: "Street Light"}) * ``` * - * @param defaultValue A string - * @param options An object like `{[value]: Label}`. Example: {r: "Red", "g": "Green"} - * @param opts Extra opts - * @param opts.as Determines if editor is shown as a menu or a switch. Either 'menu' or 'switch'. Default: 'menu' * @returns A stringLiteral prop type * */ export function stringLiteral( + /** + * Default value (a string that equals one of the options) + */ defaultValue: Extract, + /** + * The options. Use the `"value": "Label"` format. + * + * An object like `{[value]: Label}`. Example: `{r: "Red", "g": "Green"}` + */ options: Opts, + /** + * opts.as Determines if editor is shown as a menu or a switch. Either 'menu' or 'switch'. Default: 'menu' + */ opts?: {as?: 'menu' | 'switch'} & PropTypeConfigOpts, ): PropTypeConfig_StringLiteral> { return { diff --git a/theatre/core/src/sequences/TheatreSequence.ts b/theatre/core/src/sequences/TheatreSequence.ts index ad12968..493327a 100644 --- a/theatre/core/src/sequences/TheatreSequence.ts +++ b/theatre/core/src/sequences/TheatreSequence.ts @@ -130,9 +130,9 @@ export interface ISequence { */ attachAudio(args: IAttachAudioArgs): Promise<{ /** - * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer AudioBuffer}. + * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBuffer | AudioBuffer}. * If `args.source` is a URL, then `decodedBuffer` would be the result - * of {@link https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/decodeAudioData audioContext.decodeAudioData()} + * of {@link https://developer.mozilla.org/en-US/docs/Web/API/BaseAudioContext/decodeAudioData | audioContext.decodeAudioData()} * on the audio file at that URL. * * If `args.source` is an `AudioBuffer`, then `decodedBuffer` would be equal to `args.source` diff --git a/theatre/core/src/sheetObjects/SheetObject.test.ts b/theatre/core/src/sheetObjects/SheetObject.test.ts index a2b3f20..e97633b 100644 --- a/theatre/core/src/sheetObjects/SheetObject.test.ts +++ b/theatre/core/src/sheetObjects/SheetObject.test.ts @@ -1,4 +1,5 @@ /** + // eslint-disable-next-line tsdoc/syntax * @jest-environment jsdom */ import {setupTestSheet} from '@theatre/shared/testUtils' diff --git a/theatre/core/src/sheetObjects/SheetObject.ts b/theatre/core/src/sheetObjects/SheetObject.ts index 045d754..6d4ed44 100644 --- a/theatre/core/src/sheetObjects/SheetObject.ts +++ b/theatre/core/src/sheetObjects/SheetObject.ts @@ -121,7 +121,8 @@ export default class SheetObject implements IdentityDerivationProvider { getIdentityDerivation(path: Array): IDerivation { /** - * @todo perf: Too much indirection here. + * @remarks + * TODO perf: Too much indirection here. */ return prism(() => { const allValuesP = val(this.getValues()) diff --git a/theatre/core/src/sheetObjects/SheetObjectTemplate.test.ts b/theatre/core/src/sheetObjects/SheetObjectTemplate.test.ts index 091c0d4..0ca779f 100644 --- a/theatre/core/src/sheetObjects/SheetObjectTemplate.test.ts +++ b/theatre/core/src/sheetObjects/SheetObjectTemplate.test.ts @@ -1,4 +1,5 @@ /** + // eslint-disable-next-line tsdoc/syntax * @jest-environment jsdom */ import {setupTestSheet} from '@theatre/shared/testUtils' diff --git a/theatre/core/src/sheets/TheatreSheet.ts b/theatre/core/src/sheets/TheatreSheet.ts index f2673fb..842fe7d 100644 --- a/theatre/core/src/sheets/TheatreSheet.ts +++ b/theatre/core/src/sheets/TheatreSheet.ts @@ -40,8 +40,8 @@ export interface ISheet { * * **Docs: https://docs.theatrejs.com/in-depth/#objects** * - * @param key Each object is identified by a key, which is a non-empty string - * @param props The props of the object. See examples + * @param key - Each object is identified by a key, which is a non-empty string + * @param props - The props of the object. See examples * * @returns An Object * diff --git a/theatre/devEnv/buildUtils.ts b/theatre/devEnv/buildUtils.ts index 16b5ba5..999bc16 100644 --- a/theatre/devEnv/buildUtils.ts +++ b/theatre/devEnv/buildUtils.ts @@ -24,15 +24,15 @@ export function createBundles(watch: boolean) { /** * Prevents double-bundling react. * - * @notes + * @remarks * Ideally we'd want to just bundle our own fixed version of react to keep things * simple, but for now we keep react external because we're exposing these - * react-dependant API from @theatre/studio: + * react-dependant API from \@theatre/studio: * - * - ToolbarIconButton - * - IStudio['extend']({globalToolbar: {component}}) + * - `ToolbarIconButton` + * - `IStudio['extend']({globalToolbar: {component}})` * - * These are further exposed by @theatre/r3f which provides `` + * These are further exposed by \@theatre/r3f which provides `` * as an API. * * It's probably possible to bundle our own react version and somehow share it @@ -58,11 +58,11 @@ export function createBundles(watch: boolean) { }) /** - * @notes + * @remarks * I just disabled ESM builds because I couldn't get them to work * with create-react-app which uses webpack v4. I'm sure that's fixable, * but not worth the hassle right now. There is not much to tree-shake - * in @theatre/core as we've done all the tree-shaking pre-bundle already. + * in \@theatre/core as we've done all the tree-shaking pre-bundle already. */ // build({ diff --git a/theatre/shared/src/instanceTypes.ts b/theatre/shared/src/instanceTypes.ts index b664123..ad30c34 100644 --- a/theatre/shared/src/instanceTypes.ts +++ b/theatre/shared/src/instanceTypes.ts @@ -7,7 +7,7 @@ import type SheetTemplate from '@theatre/core/sheets/SheetTemplate' import type {$IntentionalAny} from './utils/types' /** - * Since @theatre/core and @theatre/studio are separate bundles, + * Since \@theatre/core and \@theatre/studio are separate bundles, * they cannot use `x instanceof Y` to detect object types. * * The functions in this module are supposed to be a replacement for that. diff --git a/theatre/shared/src/utils/minimalOverride.ts b/theatre/shared/src/utils/minimalOverride.ts index 4814aec..2df3480 100644 --- a/theatre/shared/src/utils/minimalOverride.ts +++ b/theatre/shared/src/utils/minimalOverride.ts @@ -22,7 +22,8 @@ function typeOfValue(v: unknown): ValueType { } /** - * @todo explain what this does. + * @remarks + * TODO explain what this does. */ export default function minimalOverride(base: T, override: T): T { const typeofOverride = typeOfValue(override) diff --git a/theatre/shared/src/utils/numberRoundingUtils.ts b/theatre/shared/src/utils/numberRoundingUtils.ts index c01cbfa..b72b2ca 100644 --- a/theatre/shared/src/utils/numberRoundingUtils.ts +++ b/theatre/shared/src/utils/numberRoundingUtils.ts @@ -124,7 +124,7 @@ export const stringifyNumber = (n: number): string => { } /** - * it is expected that both args are 0 < arg < 1 + * it is expected that both args are 0 \< arg \< 1 */ export const roundestFloat = (a: number, b: number): number => { const inString = { diff --git a/theatre/shared/src/utils/types.ts b/theatre/shared/src/utils/types.ts index ee64aab..cda2c3b 100644 --- a/theatre/shared/src/utils/types.ts +++ b/theatre/shared/src/utils/types.ts @@ -32,7 +32,7 @@ export type StrictRecord = {[K in Key]?: V} * This is supposed to create an "opaque" or "nominal" type, but since typescript * doesn't allow generic index signatures, we're leaving it be. * - * @todo fix this once https://github.com/microsoft/TypeScript/pull/26797 lands (likely typescript 4.4) + * TODO fix this once https://github.com/microsoft/TypeScript/pull/26797 lands (likely typescript 4.4) */ export type Nominal = T diff --git a/theatre/studio/src/Scrub.ts b/theatre/studio/src/Scrub.ts index 3f7532f..1bb196f 100644 --- a/theatre/studio/src/Scrub.ts +++ b/theatre/studio/src/Scrub.ts @@ -45,8 +45,8 @@ 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. + * @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(pointer: Pointer, value: T): void } diff --git a/theatre/studio/src/Studio.ts b/theatre/studio/src/Studio.ts index 97e3a0f..b30923f 100644 --- a/theatre/studio/src/Studio.ts +++ b/theatre/studio/src/Studio.ts @@ -59,7 +59,8 @@ export class Studio { this.paneManager = new PaneManager(this) /** - * @todo If studio.initialize() is not called within a few milliseconds, + * @remarks + * TODO If studio.initialize() is not called within a few milliseconds, * we should console.warn() the user that `@theatre/studio` is still in * their bundle. This way we can avoid issues like * [this](https://discord.com/channels/870988717190426644/892469755225710642/892479678797971486). diff --git a/theatre/studio/src/TheatreStudio.ts b/theatre/studio/src/TheatreStudio.ts index 50c6e8c..b50cc5a 100644 --- a/theatre/studio/src/TheatreStudio.ts +++ b/theatre/studio/src/TheatreStudio.ts @@ -52,7 +52,7 @@ export interface ITransactionAPI { * set(obj.props) * }) * ``` - * @param pointer A pointer, like object.props + * @param pointer - A pointer, like object.props */ unset(pointer: Pointer): void } diff --git a/theatre/studio/src/index.ts b/theatre/studio/src/index.ts index 1718e12..a561304 100644 --- a/theatre/studio/src/index.ts +++ b/theatre/studio/src/index.ts @@ -1,6 +1,3 @@ -/** - * @module @theatre/studio - */ import {setStudio} from '@theatre/studio/getStudio' import {Studio} from '@theatre/studio/Studio' diff --git a/theatre/studio/src/panels/BasePanel/PaneWrapper.tsx b/theatre/studio/src/panels/BasePanel/PaneWrapper.tsx index 6e3c2b6..7d11807 100644 --- a/theatre/studio/src/panels/BasePanel/PaneWrapper.tsx +++ b/theatre/studio/src/panels/BasePanel/PaneWrapper.tsx @@ -82,7 +82,7 @@ const ClosePanelButton = styled.button` * pane when a drag gesture is active in theatre's UI. It's a hack and its downside * is that pane content cannot interact with the rest of theatre's UI while a drag * gesture is active. - * @todo find a less hacky way? + * TODO find a less hacky way? */ const F2 = styled(F2Impl)` position: relative; diff --git a/theatre/studio/src/panels/SequenceEditorPanel/GraphEditor/BasicKeyframedTrack/KeyframeEditor/Curve.tsx b/theatre/studio/src/panels/SequenceEditorPanel/GraphEditor/BasicKeyframedTrack/KeyframeEditor/Curve.tsx index a611af7..0fe1177 100644 --- a/theatre/studio/src/panels/SequenceEditorPanel/GraphEditor/BasicKeyframedTrack/KeyframeEditor/Curve.tsx +++ b/theatre/studio/src/panels/SequenceEditorPanel/GraphEditor/BasicKeyframedTrack/KeyframeEditor/Curve.tsx @@ -68,10 +68,10 @@ const Curve: React.FC = (props) => { } /** - * Assuming a box such that: {x: 0, y: 0, width: 1px, height: 1px} + * Assuming a box such that: `{x: 0, y: 0, width: 1px, height: 1px}` * and given the desired coordinates of: - * {x: xInUnitSpace, y: yInExtremumSpace, width: widthInUnitSpace, height: heightInExtremumSpace}, - * transformBox() returns a CSS transform that transforms the box into its right dimensions + * `{x: xInUnitSpace, y: yInExtremumSpace, width: widthInUnitSpace, height: heightInExtremumSpace}`, + * `transformBox()` returns a CSS transform that transforms the box into its right dimensions * in the GraphEditor space. */ export function transformBox( diff --git a/theatre/studio/src/studioTicker.ts b/theatre/studio/src/studioTicker.ts index d43dbe1..afaf958 100644 --- a/theatre/studio/src/studioTicker.ts +++ b/theatre/studio/src/studioTicker.ts @@ -5,7 +5,7 @@ const studioTicker = new Ticker() export default studioTicker /** - * @todo users should also be able to define their own ticker. + * TODO users should also be able to define their own ticker. */ const onAnimationFrame = (t: number) => { studioTicker.tick(t) diff --git a/theatre/studio/src/uiComponents/DraggableArea.tsx b/theatre/studio/src/uiComponents/DraggableArea.tsx index 1d37da5..8c3fb29 100644 --- a/theatre/studio/src/uiComponents/DraggableArea.tsx +++ b/theatre/studio/src/uiComponents/DraggableArea.tsx @@ -42,7 +42,7 @@ type State = { } /** - * @todo low-hanging-fruit replace all DraggableArea instances with `react-use-gesture` + * TODO low-hanging-fruit replace all DraggableArea instances with `react-use-gesture` */ class DraggableArea extends React.PureComponent { s: State diff --git a/theatre/studio/src/uiComponents/selects/BasicSelect.tsx b/theatre/studio/src/uiComponents/selects/BasicSelect.tsx index 1a52c30..f4fed80 100644 --- a/theatre/studio/src/uiComponents/selects/BasicSelect.tsx +++ b/theatre/studio/src/uiComponents/selects/BasicSelect.tsx @@ -22,9 +22,6 @@ type Option = { value: string } -/** - * @todo Implement me - */ const BasicSelect: React.FC<{ label: string | ElementType options: Array