From bfba6a95eeb4e0b68b9c46b1f2ece765c002e625 Mon Sep 17 00:00:00 2001 From: Marc Rousavy Date: Mon, 8 Mar 2021 18:51:53 +0100 Subject: [PATCH] Use `@linkcode` for typedocs --- src/Camera.tsx | 67 ++++++++++++++++++++++++----------- src/CameraDevice.ts | 10 +++--- src/CameraError.ts | 14 +++++--- src/PhotoFile.ts | 6 ++-- src/Snapshot.ts | 2 +- src/VideoFile.ts | 2 +- src/hooks/useCameraDevices.ts | 12 +++---- src/utils/FormatFilter.ts | 2 +- 8 files changed, 73 insertions(+), 42 deletions(-) diff --git a/src/Camera.tsx b/src/Camera.tsx index 01be1ae..b7c91f6 100644 --- a/src/Camera.tsx +++ b/src/Camera.tsx @@ -73,7 +73,24 @@ export type CameraScannerProps = Modify< export interface CameraDeviceProps { // Properties /** - * The Camera Device to use + * The Camera Device to use. + * + * See the [Camera Devices](https://cuvent.github.io/react-native-vision-camera/docs/devices) section in the documentation for more information about Camera Devices. + * + * @example + * ```js + * const devices = useCameraDevices('wide-angle-camera') + * const device = devices.back + * + * return ( + * + * ) + * + * ``` */ device: CameraDevice; /** @@ -101,7 +118,7 @@ export interface CameraDeviceProps { export interface CameraDynamicProps { /** - * Whether the Camera should actively stream video frames, or not. + * Whether the Camera should actively stream video frames, or not. See the [documentation about the `isActive` prop](https://cuvent.github.io/react-native-vision-camera/docs/devices#the-isactive-prop) for more information. * * This can be compared to a Video component, where `isActive` specifies whether the video is paused or not. * @@ -125,7 +142,9 @@ export interface CameraDynamicProps { */ zoom?: number; /** - * Enables or disables the native pinch to zoom gesture + * Enables or disables the native pinch to zoom gesture. + * + * If you want to implement a custom zoom gesture, see [the Zooming with Reanimated documentation](https://cuvent.github.io/react-native-vision-camera/docs/animated). * * @default false */ @@ -181,10 +200,12 @@ type RefType = React.Component & Readonly; /** * ### A powerful `` component. * + * Read the [VisionCamera documentation](https://cuvent.github.io/react-native-vision-camera/) for more information. + * * The `` component's most important (and therefore _required_) properties are: * - * * {@link CameraDeviceProps.device}: Specifies the {@link CameraDevice} to use. Get a {@link CameraDevice} by using the {@link useCameraDevices} hook, or manually by using the {@link Camera.getAvailableCameraDevices} function. - * * {@link CameraDynamicProps.isActive}: A boolean value that specifies whether the Camera should actively stream video frames or not. This can be compared to a Video component, where `isActive` specifies whether the video is paused or not. If you fully unmount the `` component instead of using `isActive={false}`, the Camera will take a bit longer to start again. + * * {@linkcode CameraDeviceProps.device | device}: Specifies the {@linkcode CameraDevice} to use. Get a {@linkcode CameraDevice} by using the {@linkcode useCameraDevices | useCameraDevices()} hook, or manually by using the {@linkcode Camera.getAvailableCameraDevices Camera.getAvailableCameraDevices()} function. + * * {@linkcode CameraDynamicProps.isActive | isActive}: A boolean value that specifies whether the Camera should actively stream video frames or not. This can be compared to a Video component, where `isActive` specifies whether the video is paused or not. If you fully unmount the `` component instead of using `isActive={false}`, the Camera will take a bit longer to start again. * * @example * ```jsx @@ -240,7 +261,7 @@ export class Camera extends React.PureComponent { /** * Take a single photo and write it's content to a temporary file. * - * @throws {@link CameraCaptureError} When any kind of error occured. Use the {@link CameraCaptureError.code} property to get the actual error + * @throws {@linkcode CameraCaptureError} When any kind of error occured while capturing the photo. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error * @example * ```js * const photo = await camera.current.takePhoto({ @@ -261,7 +282,9 @@ export class Camera extends React.PureComponent { /** * Take a snapshot of the current preview view. * - * This can be used as an alternative to {@link Camera.takePhoto} if speed is more important than quality + * This can be used as an alternative to {@linkcode Camera.takePhoto | takePhoto()} if speed is more important than quality + * + * @throws {@linkcode CameraCaptureError} When any kind of error occured while taking a snapshot. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error * * @platform Android * @example @@ -292,7 +315,7 @@ export class Camera extends React.PureComponent { * * @blocking This function is synchronized/blocking. * - * @throws {@link CameraCaptureError} When any kind of error occured. Use the {@link CameraCaptureError.code} property to get the actual error + * @throws {@linkcode CameraCaptureError} When any kind of error occured while starting the video recording. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error * * @example * ```js @@ -324,7 +347,7 @@ export class Camera extends React.PureComponent { /** * Stop the current video recording. * - * @throws {@link CameraCaptureError} When any kind of error occured. Use the {@link CameraCaptureError.code} property to get the actual error + * @throws {@linkcode CameraCaptureError} When any kind of error occured while stopping the video recording. Use the {@linkcode CameraCaptureError.code | code} property to get the actual error * * @example * ```js @@ -351,7 +374,7 @@ export class Camera extends React.PureComponent { * * Make sure the value doesn't exceed the CameraView's dimensions. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while focussing. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error * @example * ```js * await camera.current.focus({ @@ -372,9 +395,10 @@ export class Camera extends React.PureComponent { * Get a list of video codecs the current camera supports. Returned values are ordered by efficiency (descending). * * This function can only be called after the camera has been initialized, - * so only use this after the {@link onInitialized} event has fired. + * so only use this after the {@linkcode onInitialized | onInitialized()} event has fired. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @platform iOS + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting available video codecs. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error */ public async getAvailableVideoCodecs(): Promise { try { @@ -387,9 +411,10 @@ export class Camera extends React.PureComponent { * Get a list of photo codecs the current camera supports. Returned values are ordered by efficiency (descending). * * This function can only be called after the camera has been initialized, - * so only use this after the {@link onInitialized} event has fired. + * so only use this after the {@linkcode onInitialized | onInitialized()} event has fired. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @platform iOS + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting available photo codecs. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error */ public async getAvailablePhotoCodecs(): Promise { try { @@ -404,7 +429,7 @@ export class Camera extends React.PureComponent { /** * Get a list of all available camera devices on the current phone. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting all available camera devices. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error * @example * ```js * const devices = await Camera.getAvailableCameraDevices() @@ -427,9 +452,9 @@ export class Camera extends React.PureComponent { * Gets the current Camera Permission Status. Check this before mounting the Camera to ensure * the user has permitted the app to use the camera. * - * To actually prompt the user for camera permission, use {@link Camera.requestCameraPermission}. + * To actually prompt the user for camera permission, use {@linkcode Camera.requestCameraPermission | requestCameraPermission()}. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting the current permission status. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error */ public static async getCameraPermissionStatus(): Promise { try { @@ -442,9 +467,9 @@ export class Camera extends React.PureComponent { * Gets the current Microphone-Recording Permission Status. Check this before mounting the Camera to ensure * the user has permitted the app to use the microphone. * - * To actually prompt the user for microphone permission, use {@link Camera.requestMicrophonePermission}. + * To actually prompt the user for microphone permission, use {@linkcode Camera.requestMicrophonePermission | requestMicrophonePermission()}. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while getting the current permission status. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error */ public static async getMicrophonePermissionStatus(): Promise { try { @@ -459,7 +484,7 @@ export class Camera extends React.PureComponent { * If the user has previously blocked the app from using the camera, the alert will not be shown * and `"denied"` will be returned. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while requesting permission. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error */ public static async requestCameraPermission(): Promise { try { @@ -474,7 +499,7 @@ export class Camera extends React.PureComponent { * If the user has previously blocked the app from using the microphone, the alert will not be shown * and `"denied"` will be returned. * - * @throws {@link CameraRuntimeError} When any kind of error occured. Use the {@link CameraRuntimeError.code} property to get the actual error + * @throws {@linkcode CameraRuntimeError} When any kind of error occured while requesting permission. Use the {@linkcode CameraRuntimeError.code | code} property to get the actual error */ public static async requestMicrophonePermission(): Promise { try { diff --git a/src/CameraDevice.ts b/src/CameraDevice.ts index 3997bcc..efc8378 100644 --- a/src/CameraDevice.ts +++ b/src/CameraDevice.ts @@ -20,7 +20,7 @@ export type PhysicalCameraDeviceType = 'ultra-wide-angle-camera' | 'wide-angle-c export type LogicalCameraDeviceType = 'dual-camera' | 'dual-wide-camera' | 'triple-camera' | 'true-depth-camera'; /** - * Parses an array of physical device types into a single {@link PhysicalCameraDeviceType} or {@link LogicalCameraDeviceType}, depending what matches. + * Parses an array of physical device types into a single {@linkcode PhysicalCameraDeviceType} or {@linkcode LogicalCameraDeviceType}, depending what matches. * @method */ export const parsePhysicalDeviceTypes = (physicalDeviceTypes: PhysicalCameraDeviceType[]): PhysicalCameraDeviceType | LogicalCameraDeviceType => { @@ -80,7 +80,7 @@ export interface FrameRateRange { } /** - * A Camera Device's video format. Do not create instances of this type yourself, only use {@link Camera.getAvailableCameraDevices}. + * A Camera Device's video format. Do not create instances of this type yourself, only use {@linkcode Camera.getAvailableCameraDevices | Camera.getAvailableCameraDevices()}. */ export interface CameraDeviceFormat { /** @@ -154,7 +154,7 @@ export interface CameraDeviceFormat { } /** - * Represents a camera device discovered by the {@link Camera.getAvailableCameraDevices} function + * Represents a camera device discovered by the {@linkcode Camera.getAvailableCameraDevices | Camera.getAvailableCameraDevices()} function */ export interface CameraDevice { /** @@ -212,7 +212,9 @@ export interface CameraDevice { */ neutralZoom: number; /** - * All available formats for this camera device. Use this to find the best format for your use case and set it to the Camera's `format` property. + * All available formats for this camera device. Use this to find the best format for your use case and set it to the Camera's {@linkcode Camera.format} property. + * + * See [the Camera Formats documentation](https://cuvent.github.io/react-native-vision-camera/docs/formats) for more information about Camera Formats. */ formats: CameraDeviceFormat[]; /** diff --git a/src/CameraError.ts b/src/CameraError.ts index 28b4c48..b292489 100644 --- a/src/CameraError.ts +++ b/src/CameraError.ts @@ -37,7 +37,7 @@ export type SystemError = 'system/no-camera-manager'; export type UnknownError = 'unknown/unknown'; /** - * Represents a JSON-style error cause. This contains native `NSError`/`Throwable` information, and can have recursive {@link ErrorWithCause.cause} properties until the ultimate cause has been found. + * Represents a JSON-style error cause. This contains native `NSError`/`Throwable` information, and can have recursive {@linkcode ErrorWithCause.cause | .cause} properties until the ultimate cause has been found. */ export interface ErrorWithCause { /** @@ -87,7 +87,7 @@ export interface ErrorWithCause { type CameraErrorCode = PermissionError | ParameterError | DeviceError | FormatError | SessionError | CaptureError | SystemError | UnknownError; /** - * Represents any kind of error that occured in the {@link Camera} View Module. + * Represents any kind of error that occured in the {@linkcode Camera} View Module. */ class CameraError extends Error { private readonly _code: TCode; @@ -117,20 +117,24 @@ class CameraError extends Error { /** * Represents any kind of error that occured while trying to capture a video or photo. + * + * See the ["Camera Errors" documentation](https://cuvent.github.io/react-native-vision-camera/docs/errors) for more information about Camera Errors. */ export class CameraCaptureError extends CameraError {} /** * Represents any kind of error that occured in the Camera View Module. + * + * See the ["Camera Errors" documentation](https://cuvent.github.io/react-native-vision-camera/docs/errors) for more information about Camera Errors. */ export class CameraRuntimeError extends CameraError< PermissionError | ParameterError | DeviceError | FormatError | SessionError | SystemError | UnknownError > {} /** - * Checks if the given `error` is of type {@link ErrorWithCause} + * Checks if the given `error` is of type {@linkcode ErrorWithCause} * @param {unknown} error Any unknown object to validate - * @returns `true` if the given `error` is of type {@link ErrorWithCause} + * @returns `true` if the given `error` is of type {@linkcode ErrorWithCause} */ export const isErrorWithCause = (error: unknown): error is ErrorWithCause => typeof error === 'object' && @@ -155,7 +159,7 @@ const isCameraErrorJson = (error: unknown): error is { code: string; message: st /** * Tries to parse an error coming from native to a typed JS camera error. * @param {CameraError} nativeError The native error instance. This is a JSON in the legacy native module architecture. - * @returns A {@link CameraRuntimeError} or {@link CameraCaptureError}, or the `nativeError` itself if it's not parsable + * @returns A {@linkcode CameraRuntimeError} or {@linkcode CameraCaptureError}, or the `nativeError` itself if it's not parsable * @method */ export const tryParseNativeCameraError = (nativeError: T): (CameraRuntimeError | CameraCaptureError) | T => { diff --git a/src/PhotoFile.ts b/src/PhotoFile.ts index fbb0027..be54a9e 100644 --- a/src/PhotoFile.ts +++ b/src/PhotoFile.ts @@ -3,7 +3,7 @@ import type { TemporaryFile } from './TemporaryFile'; export interface TakePhotoOptions { /** - * Specify the photo codec to use. To get a list of available photo codecs use the {@link Camera.getAvailablePhotoCodecs} function. + * Specify the photo codec to use. To get a list of available photo codecs use the {@linkcode Camera.getAvailablePhotoCodecs | getAvailablePhotoCodecs()} function. * * @platform iOS * @default undefined @@ -52,7 +52,7 @@ export interface TakePhotoOptions { */ enableAutoDistortionCorrection?: boolean; /** - * When set to `true`, metadata reading and mapping will be skipped. ({@link PhotoFile.metadata} will be null) + * When set to `true`, metadata reading and mapping will be skipped. ({@linkcode PhotoFile.metadata} will be null) * * This might result in a faster capture, as metadata reading and mapping requires File IO. * @@ -66,7 +66,7 @@ export interface TakePhotoOptions { /** * Represents a Photo taken by the Camera written to the local filesystem. * - * Related: {@link Camera.takePhoto}, {@link Camera.takeSnapshot} + * Related: {@linkcode Camera.takePhoto | Camera.takePhoto()}, {@linkcode Camera.takeSnapshot | Camera.takeSnapshot()} */ export interface PhotoFile extends TemporaryFile { width: number; diff --git a/src/Snapshot.ts b/src/Snapshot.ts index bde9feb..845dc3c 100644 --- a/src/Snapshot.ts +++ b/src/Snapshot.ts @@ -9,7 +9,7 @@ export interface TakeSnapshotOptions { quality?: number; /** - * When set to `true`, metadata reading and mapping will be skipped. ({@link PhotoFile.metadata} will be `null`) + * When set to `true`, metadata reading and mapping will be skipped. ({@linkcode PhotoFile.metadata} will be `null`) * * This might result in a faster capture, as metadata reading and mapping requires File IO. * diff --git a/src/VideoFile.ts b/src/VideoFile.ts index a87dfb4..43ecdcb 100644 --- a/src/VideoFile.ts +++ b/src/VideoFile.ts @@ -47,7 +47,7 @@ export interface RecordVideoOptions { /** * Represents a Video taken by the Camera written to the local filesystem. * - * Related: {@link Camera.startRecording}, {@link Camera.stopRecording} + * Related: {@linkcode Camera.startRecording | Camera.startRecording()}, {@linkcode Camera.stopRecording | Camera.stopRecording()} */ export interface VideoFile extends TemporaryFile { /** diff --git a/src/hooks/useCameraDevices.ts b/src/hooks/useCameraDevices.ts index 2b2f7dd..1ec0992 100644 --- a/src/hooks/useCameraDevices.ts +++ b/src/hooks/useCameraDevices.ts @@ -15,10 +15,10 @@ const DefaultCameraDevices: CameraDevices = { }; /** - * Gets the best available `CameraDevice`. Devices with more cameras are preferred. + * Gets the best available {@linkcode CameraDevice}. Devices with more cameras are preferred. * - * @returns The best matching `CameraDevice`. - * @throws {@link CameraRuntimeError} if no device was found. + * @returns The best matching {@linkcode CameraDevice}. + * @throws {@linkcode CameraRuntimeError} if no device was found. * @example * ```jsx * const device = useCameraDevice() @@ -29,11 +29,11 @@ const DefaultCameraDevices: CameraDevices = { export function useCameraDevices(): CameraDevices; /** - * Gets a `CameraDevice` for the requested device type. + * Gets a {@linkcode CameraDevice} for the requested device type. * * @param {PhysicalCameraDeviceType | LogicalCameraDeviceType} deviceType Specifies a device type which will be used as a device filter. - * @returns A `CameraDevice` for the requested device type. - * @throws {@link CameraRuntimeError} if no device was found. + * @returns A {@linkcode CameraDevice} for the requested device type. + * @throws {@linkcode CameraRuntimeError} if no device was found. * @example * ```jsx * const device = useCameraDevice('wide-angle-camera') diff --git a/src/utils/FormatFilter.ts b/src/utils/FormatFilter.ts index 196287e..effd39a 100644 --- a/src/utils/FormatFilter.ts +++ b/src/utils/FormatFilter.ts @@ -79,7 +79,7 @@ const getFormatAspectRatioOverflow = (format: CameraDeviceFormat, size: Size): n /** * Filters Camera Device Formats by the best matching aspect ratio for the given `viewSize`. * - * @param {CameraDeviceFormat[]} formats A list of formats the current device has (see {@link CameraDevice.formats}) + * @param {CameraDeviceFormat[]} formats A list of formats the current device has (see {@linkcode CameraDevice.formats}) * @param {Size} viewSize The size of the camera view which will be used to find the best aspect ratio. Defaults to the screen size. * @returns A list of Camera Device Formats that match the given `viewSize`' aspect ratio _as close as possible_. *