From 1138eeba369d5767f3278fdd408c2a36e6da1265 Mon Sep 17 00:00:00 2001 From: Miron Pawlik Date: Fri, 17 Jan 2025 15:46:00 +0100 Subject: [PATCH] [FCE-1038] Update types exports (and typedoc) to make `yarn docs` happy (#247) ## Description Export all types that are visible to end user, but were not yet exported Fix typedoc syntax marked as incorrect Update typedoc config to avoid part of validation for libraries that are not actively supported ## Motivation and Context I want to update our documentation, but as part of this process I want to remove warnings (and also add missing types into docs) ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) --- .github/workflows/node.yaml | 3 +++ packages/protobufs/typedoc.json | 6 ++++++ packages/react-client/src/FishjamProvider.tsx | 3 +-- packages/react-client/src/devices/DeviceManager.ts | 3 +-- packages/react-client/src/devices/mediaInitializer.ts | 3 ++- packages/react-client/src/hooks/devices/useCamera.ts | 3 +-- .../react-client/src/hooks/devices/useMicrophone.ts | 3 +-- .../src/hooks/internal/useFishjamClientState.ts | 2 +- packages/react-client/src/hooks/useConnection.ts | 2 -- packages/react-client/src/hooks/usePeers.ts | 3 +-- packages/react-client/src/hooks/useVAD.ts | 2 +- packages/react-client/src/index.ts | 11 ++++++++++- packages/react-client/src/types/internal.ts | 11 +---------- packages/react-client/src/types/public.ts | 11 ++++++++++- packages/react-client/src/utils/errors.ts | 2 +- packages/react-client/typedoc.json | 5 ++++- packages/ts-client/src/FishjamClient.ts | 3 +-- packages/ts-client/src/index.ts | 2 +- packages/ts-client/src/types.ts | 2 +- packages/webrtc-client/src/webRTCEndpoint.ts | 1 - packages/webrtc-client/typedoc.json | 5 ++++- typedoc.json | 4 +++- 22 files changed, 54 insertions(+), 36 deletions(-) create mode 100644 packages/protobufs/typedoc.json diff --git a/.github/workflows/node.yaml b/.github/workflows/node.yaml index f4be4c792..95acc8f02 100644 --- a/.github/workflows/node.yaml +++ b/.github/workflows/node.yaml @@ -45,3 +45,6 @@ jobs: - name: Run typecheck 🚓 run: yarn tsc + + - name: Run docs generation 📘 + run: yarn docs diff --git a/packages/protobufs/typedoc.json b/packages/protobufs/typedoc.json new file mode 100644 index 000000000..5a377bef6 --- /dev/null +++ b/packages/protobufs/typedoc.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "validation": { + "notExported": false + } +} diff --git a/packages/react-client/src/FishjamProvider.tsx b/packages/react-client/src/FishjamProvider.tsx index 15e048959..dcd26eba7 100644 --- a/packages/react-client/src/FishjamProvider.tsx +++ b/packages/react-client/src/FishjamProvider.tsx @@ -24,7 +24,7 @@ export interface FishjamProviderProps extends PropsWithChildren { /** * Set preferred constraints. * @param {MediaStreamConstraints} constraints - The media stream constraints as defined by the Web API. - * @external {@link https://udn.realityripple.com/docs/Web/API/MediaStreamConstraints MediaStreamConstraints} + * @see {@link https://udn.realityripple.com/docs/Web/API/MediaStreamConstraints MediaStreamConstraints} */ constraints?: Pick; /** @@ -49,7 +49,6 @@ export interface FishjamProviderProps extends PropsWithChildren { /** * Provides the Fishjam Context * @category Components - * @param */ export function FishjamProvider(props: FishjamProviderProps) { const fishjamClientRef = useRef(new FishjamClient({ reconnect: props.reconnect })); diff --git a/packages/react-client/src/devices/DeviceManager.ts b/packages/react-client/src/devices/DeviceManager.ts index 51e756cef..b1266bb03 100644 --- a/packages/react-client/src/devices/DeviceManager.ts +++ b/packages/react-client/src/devices/DeviceManager.ts @@ -2,7 +2,6 @@ import EventEmitter from "events"; import type TypedEmitter from "typed-emitter"; import type { - DeviceError, DeviceManagerStatus, DevicesStatus, DeviceState, @@ -10,7 +9,7 @@ import type { MediaManager, MediaStatus, } from "../types/internal"; -import type { DeviceType, PersistLastDeviceHandlers, TrackMiddleware } from "../types/public"; +import type { DeviceError, DeviceType, PersistLastDeviceHandlers, TrackMiddleware } from "../types/public"; import { parseUserMediaError } from "../utils/errors"; import { createStorageConfig } from "../utils/localStorage"; import { setupOnEndedCallback } from "../utils/track"; diff --git a/packages/react-client/src/devices/mediaInitializer.ts b/packages/react-client/src/devices/mediaInitializer.ts index 633c530c9..bae96cf7a 100644 --- a/packages/react-client/src/devices/mediaInitializer.ts +++ b/packages/react-client/src/devices/mediaInitializer.ts @@ -1,4 +1,5 @@ -import type { CurrentDevices, DeviceError } from "../types/internal"; +import type { CurrentDevices } from "../types/internal"; +import type { DeviceError } from "../types/public"; import { NOT_FOUND_ERROR, OVERCONSTRAINED_ERROR, PERMISSION_DENIED, UNHANDLED_ERROR } from "../utils/errors"; import { prepareConstraints } from "./constraints"; diff --git a/packages/react-client/src/hooks/devices/useCamera.ts b/packages/react-client/src/hooks/devices/useCamera.ts index ad469054b..af630c345 100644 --- a/packages/react-client/src/hooks/devices/useCamera.ts +++ b/packages/react-client/src/hooks/devices/useCamera.ts @@ -1,5 +1,4 @@ -import type { DeviceError } from "../../types/internal"; -import type { DeviceItem, TrackMiddleware } from "../../types/public"; +import type { DeviceError, DeviceItem, TrackMiddleware } from "../../types/public"; import { useDeviceApi } from "../internal/device/useDeviceApi"; import { useFishjamContext } from "../internal/useFishjamContext"; diff --git a/packages/react-client/src/hooks/devices/useMicrophone.ts b/packages/react-client/src/hooks/devices/useMicrophone.ts index ee34f91bb..f01b4f537 100644 --- a/packages/react-client/src/hooks/devices/useMicrophone.ts +++ b/packages/react-client/src/hooks/devices/useMicrophone.ts @@ -1,5 +1,4 @@ -import type { DeviceError } from "../../types/internal"; -import type { DeviceItem, TrackMiddleware } from "../../types/public"; +import type { DeviceError, DeviceItem, TrackMiddleware } from "../../types/public"; import { useDeviceApi } from "../internal/device/useDeviceApi"; import { useFishjamContext } from "../internal/useFishjamContext"; diff --git a/packages/react-client/src/hooks/internal/useFishjamClientState.ts b/packages/react-client/src/hooks/internal/useFishjamClientState.ts index 71b6ef3ed..ecf197fc6 100644 --- a/packages/react-client/src/hooks/internal/useFishjamClientState.ts +++ b/packages/react-client/src/hooks/internal/useFishjamClientState.ts @@ -1,7 +1,7 @@ import type { Component, FishjamClient, GenericMetadata, MessageEvents, Peer } from "@fishjam-cloud/ts-client"; import { useCallback, useMemo, useRef, useSyncExternalStore } from "react"; -import type { PeerId } from "../../types/internal"; +import type { PeerId } from "../../types/public"; const eventNames = [ "socketClose", diff --git a/packages/react-client/src/hooks/useConnection.ts b/packages/react-client/src/hooks/useConnection.ts index 29f21d1c6..bb211bcc3 100644 --- a/packages/react-client/src/hooks/useConnection.ts +++ b/packages/react-client/src/hooks/useConnection.ts @@ -26,8 +26,6 @@ export interface JoinRoomConfig( config: JoinRoomConfig, diff --git a/packages/react-client/src/hooks/usePeers.ts b/packages/react-client/src/hooks/usePeers.ts index 61fc549cf..669f7cb61 100644 --- a/packages/react-client/src/hooks/usePeers.ts +++ b/packages/react-client/src/hooks/usePeers.ts @@ -8,8 +8,7 @@ import type { TrackMetadata, } from "@fishjam-cloud/ts-client"; -import type { PeerId } from "../types/internal"; -import type { Track } from "../types/public"; +import type { PeerId, Track } from "../types/public"; import { useFishjamContext } from "./internal/useFishjamContext"; /** diff --git a/packages/react-client/src/hooks/useVAD.ts b/packages/react-client/src/hooks/useVAD.ts index 9e61560ad..2b1682fea 100644 --- a/packages/react-client/src/hooks/useVAD.ts +++ b/packages/react-client/src/hooks/useVAD.ts @@ -1,7 +1,7 @@ import type { TrackContext, VadStatus } from "@fishjam-cloud/ts-client"; import { useEffect, useMemo, useState } from "react"; -import type { PeerId, TrackId } from "../types/internal"; +import type { PeerId, TrackId } from "../types/public"; import { useFishjamClientState } from "./internal/useFishjamClientState"; import { useFishjamContext } from "./internal/useFishjamContext"; diff --git a/packages/react-client/src/index.ts b/packages/react-client/src/index.ts index 610a05f54..7c3a47bfa 100644 --- a/packages/react-client/src/index.ts +++ b/packages/react-client/src/index.ts @@ -1,6 +1,10 @@ export { FishjamProvider, type FishjamProviderProps } from "./FishjamProvider"; export { useCamera, type UseCameraResult } from "./hooks/devices/useCamera"; -export { useInitializeDevices, type UseInitializeDevicesResult } from "./hooks/devices/useInitializeDevices"; +export { + useInitializeDevices, + type UseInitializeDevicesParams, + type UseInitializeDevicesResult, +} from "./hooks/devices/useInitializeDevices"; export { useMicrophone, type UseMicrophoneResult } from "./hooks/devices/useMicrophone"; export { type JoinRoomConfig, useConnection, type UseConnectionResult } from "./hooks/useConnection"; export { type PeerWithTracks, usePeers, type UsePeersResult } from "./hooks/usePeers"; @@ -8,11 +12,16 @@ export { useScreenShare, type UseScreenshareResult } from "./hooks/useScreenShar export { useUpdatePeerMetadata } from "./hooks/useUpdatePeerMetadata"; export { useVAD } from "./hooks/useVAD"; export type { + BandwidthLimits, + DeviceError, DeviceItem, + PeerId, PeerStatus, PersistLastDeviceHandlers, + SimulcastBandwidthLimits, StreamConfig, Track, + TrackId, TrackMiddleware, TracksMiddleware, } from "./types/public"; diff --git a/packages/react-client/src/types/internal.ts b/packages/react-client/src/types/internal.ts index 82e7a2b10..68c1b8dd1 100644 --- a/packages/react-client/src/types/internal.ts +++ b/packages/react-client/src/types/internal.ts @@ -1,7 +1,4 @@ -import type { DeviceType, Track, TrackMiddleware, TracksMiddleware } from "./public"; - -export type TrackId = string; -export type PeerId = string; +import type { DeviceError, DeviceType, Track, TrackMiddleware, TracksMiddleware } from "./public"; export type DevicesStatus = "OK" | "Error" | "Not requested" | "Requesting"; export type MediaStatus = "OK" | "Error" | "Not requested" | "Requesting"; @@ -30,12 +27,6 @@ export type DeviceState = { currentMiddleware: TrackMiddleware | null; }; -export type DeviceError = - | { name: "OverconstrainedError" } - | { name: "NotAllowedError" } - | { name: "NotFoundError" } - | { name: "UNHANDLED_ERROR" }; - export type CurrentDevices = { videoinput: MediaDeviceInfo | null; audioinput: MediaDeviceInfo | null }; export interface MediaManager { diff --git a/packages/react-client/src/types/public.ts b/packages/react-client/src/types/public.ts index 730f89a5f..ece37dc39 100644 --- a/packages/react-client/src/types/public.ts +++ b/packages/react-client/src/types/public.ts @@ -1,6 +1,9 @@ import type { SimulcastConfig, TrackMetadata, Variant } from "@fishjam-cloud/ts-client"; -import type { DeviceError, DeviceManagerStatus, TrackId } from "./internal"; +import type { DeviceManagerStatus } from "./internal"; + +export type TrackId = string; +export type PeerId = string; export type Track = { stream: MediaStream | null; @@ -57,3 +60,9 @@ export type StreamConfig = { simulcast?: Variant[] | false }; export type BandwidthLimits = { singleStream: number; simulcast: SimulcastBandwidthLimits }; export type DeviceType = "audio" | "video"; + +export type DeviceError = + | { name: "OverconstrainedError" } + | { name: "NotAllowedError" } + | { name: "NotFoundError" } + | { name: "UNHANDLED_ERROR" }; diff --git a/packages/react-client/src/utils/errors.ts b/packages/react-client/src/utils/errors.ts index 5c7d5ffa7..ff873573a 100644 --- a/packages/react-client/src/utils/errors.ts +++ b/packages/react-client/src/utils/errors.ts @@ -1,4 +1,4 @@ -import type { DeviceError } from "../types/internal"; +import type { DeviceError } from "../types/public"; export const PERMISSION_DENIED: DeviceError = { name: "NotAllowedError" }; export const OVERCONSTRAINED_ERROR: DeviceError = { name: "OverconstrainedError" }; diff --git a/packages/react-client/typedoc.json b/packages/react-client/typedoc.json index 5f4a0e52b..53682ac5b 100644 --- a/packages/react-client/typedoc.json +++ b/packages/react-client/typedoc.json @@ -5,5 +5,8 @@ "categoryOrder": ["Connection", "Devices", "Screenshare", "Components", "*", "Debugging"], "sort": ["kind", "alphabetical"], "kindSortOrder": ["Method", "Function"], - "readme": "none" + "readme": "none", + "validation": { + "notExported": true + } } diff --git a/packages/ts-client/src/FishjamClient.ts b/packages/ts-client/src/FishjamClient.ts index 566630897..7ecaa060f 100644 --- a/packages/ts-client/src/FishjamClient.ts +++ b/packages/ts-client/src/FishjamClient.ts @@ -101,7 +101,7 @@ export class FishjamClient} * - * @external RTCPeerConnection#getStats() * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/getStats | MDN Web Docs: RTCPeerConnection.getStats()} */ public async getStatistics(selector?: MediaStreamTrack | null): Promise { diff --git a/packages/ts-client/src/index.ts b/packages/ts-client/src/index.ts index ea7ab1a82..d5d98b022 100644 --- a/packages/ts-client/src/index.ts +++ b/packages/ts-client/src/index.ts @@ -11,6 +11,7 @@ export type { MessageEvents, Metadata, Peer, + TrackContextEvents, TrackMetadata, } from './types'; export type { @@ -21,7 +22,6 @@ export type { SimulcastConfig, TrackBandwidthLimit, TrackContext, - TrackContextEvents, VadStatus, WebRTCEndpointEvents, } from '@fishjam-cloud/webrtc-client'; diff --git a/packages/ts-client/src/types.ts b/packages/ts-client/src/types.ts index 923cbaf5c..f1bcf16ff 100644 --- a/packages/ts-client/src/types.ts +++ b/packages/ts-client/src/types.ts @@ -32,7 +32,7 @@ export type Metadata void; voiceActivityChanged: (context: FishjamTrackContext) => void; }; diff --git a/packages/webrtc-client/src/webRTCEndpoint.ts b/packages/webrtc-client/src/webRTCEndpoint.ts index 9d93064cd..19e6871e0 100644 --- a/packages/webrtc-client/src/webRTCEndpoint.ts +++ b/packages/webrtc-client/src/webRTCEndpoint.ts @@ -157,7 +157,6 @@ export class WebRTCEndpoint extends (EventEmitter as new () => TypedEmitter} * - * @external RTCPeerConnection#getStats() * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/getStats | MDN Web Docs: RTCPeerConnection.getStats()} */ public async getStatistics(selector?: MediaStreamTrack | null): Promise { diff --git a/packages/webrtc-client/typedoc.json b/packages/webrtc-client/typedoc.json index c00c1b566..86e9a845c 100644 --- a/packages/webrtc-client/typedoc.json +++ b/packages/webrtc-client/typedoc.json @@ -2,5 +2,8 @@ "$schema": "https://typedoc.org/schema.json", "includeVersion": true, "entryPoints": ["src/index.ts"], - "readme": "none" + "readme": "none", + "validation": { + "notExported": false + } } diff --git a/typedoc.json b/typedoc.json index ac6afc455..493b22e59 100644 --- a/typedoc.json +++ b/typedoc.json @@ -6,5 +6,7 @@ "plugin": ["typedoc-material-theme"], "themeColor": "#FCF6E7", "sort": ["kind", "alphabetical"], - "kindSortOrder": ["Method", "Function"] + "kindSortOrder": ["Method", "Function"], + "treatValidationWarningsAsErrors": true, + "treatWarningsAsErrors": true }