expo-api-docs

Documenting Expo APIs

Guidelines for writing TSDoc comments in Expo SDK packages. The docs generation system (GenerateDocsAPIData.ts + TypeDoc) extracts these comments to produce API reference documentation.

Document APIs as you write them, not as an afterthought. When implementing new features, write TSDoc comments alongside the code.

When to Use

• Implementing new features that expose public TypeScript APIs
• Adding or modifying public APIs in packages/expo-*
• Documenting functions, types, interfaces, constants, or enums
• Adding platform-specific annotations
• Writing code examples in docblocks

Core Principles

1. Third-person declarative — describe what the function does, not what to do
2. Explain the iceberg — document failure modes, side effects, concurrency behavior, not just params/returns
3. Quality over quantity — no docs is better than useless docs like "The width" for a width property

Function Documentation

Use third-person declarative ("Gets...", "Returns...", "Checks..."), not imperative ("Get...", "Return...").

/**
 * Gets the uptime since the last reboot of the device, in milliseconds.
 * Android devices do not count time spent in deep sleep.
 *
 * @return A promise fulfilled with the milliseconds since last reboot.
 *
 * @example
 * ```ts
 * const uptime = await Device.getUptimeAsync();
 * // 4371054
 * ```
 *
 * @platform android
 * @platform ios
 */
export async function getUptimeAsync(): Promise<number> {

Key points:

• First sentence: what the function does
• Additional sentences: important behavior, edge cases, platform differences
• Leave off trailing period for single-phrase descriptions
• Use periods when writing multiple sentences

Parameter Documentation

/**
 * Sets the sensor update interval.
 *
 * @param intervalMs Desired interval in milliseconds between sensor updates.
 * > Starting from Android 12 (API level 31), the system has a 200Hz limit for each sensor updates.
 * >
 * > If you need an update interval less than 5ms, add `android.permission.HIGH_SAMPLING_RATE_SENSORS`
 * > to [**app.json** `permissions` field](/versions/latest/config/app/#permissions).
 */
setUpdateInterval(intervalMs: number): void {

Format: @param paramName Description starting with capital letter

Parameters can include:

• Markdown formatting (links, emphasis, lists)
• Blockquotes for important notes
• Links to documentation pages

Type and Interface Documentation

Document each property individually:

export type GetImageOptions = {
  /**
   * The format of the clipboard image to be converted to.
   */
  format: 'png' | 'jpeg';
  /**
   * Specify the quality of the returned image, between `0` and `1`.
   * Applicable only when `format` is set to `jpeg`, ignored otherwise.
   * @default 1
   */
  jpegQuality?: number;
};

Teach something useful. Bad: "The width". Good: "The width of the captured photo, measured in pixels".

Supported TSDoc Tags

Platform tag notes:

• Do NOT use @platform when all platforms are supported — only add when limiting availability
• Use multiple @platform tags for multiple platforms (one per line)
• Can specify minimum version: @platform ios 11+
• Available platforms: android, ios, web, expo (Expo Go)

Code Examples in Docblocks

Always wrap in triple backticks with language tag:

/**
 * Checks device root/jailbreak status.
 *
 * @example
 * ```ts
 * const isRooted = await Device.isRootedExperimentalAsync();
 * if (isRooted) {
 *   console.warn('Device may be compromised');
 * }
 * ```
 */

Blockquote Notes and Warnings

Use > blockquotes for important callouts:

/**
 * > **Note:** This method requires the `CAMERA` permission.
 *
 * > **warning** This method is experimental and not completely reliable.
 */

Formats:

• > **Note:** — informational
• > **warning** — caution (lowercase "warning")
• Multi-line notes use > on each line with blank > between paragraphs

Constant Documentation

/**
 * `true` if the app is running on a real device and `false` if running
 * in a simulator or emulator. On web, this is always set to `true`.
 */
export const isDevice: boolean = ExpoDevice.isDevice;

Enum Documentation

Document the enum and individual values:

/**
 * Type used to define what type of data is stored in the clipboard.
 */
export enum ContentType {
  PLAIN_TEXT = 'plain-text',
  HTML = 'html',
  IMAGE = 'image',
  /**
   * @platform iOS
   */
  URL = 'url',
}

Return Value Language

Use "resolves to" in @returns tags, following MDN's convention:

• Preferred: @returns A promise that resolves to a CameraPhoto object.
• Also acceptable: @returns A promise fulfilled with a CameraPhoto object.

In inline prose, "resolves with" is acceptable (e.g. "The promise resolves with the parsed result").

Type Export Patterns

Critical: Types must be exported from the entry point file for docs generation to pick them up.

Direct re-export from types file:

// index.ts or MainModule.ts
export {
  type FileCreateOptions,
  type DirectoryCreateOptions,
  type FileHandle,
} from './Module.types';

Re-export after import:

// Haptics.ts
import { NotificationFeedbackType, ImpactFeedbackStyle } from './Haptics.types';

// ... function implementations ...

export { NotificationFeedbackType, ImpactFeedbackStyle };

The GenerateDocsAPIData script processes the entry point specified in its package mapping and extracts all publicly exported symbols.

Writing Usage Examples (for .mdx docs)

When writing examples in documentation pages:

Code Block Format

```ts app/(tabs)/index.tsx
import * as FileSystem from 'expo-file-system';

const content = await FileSystem.readAsStringAsync(uri);

Always include:
- Language tag (`ts`, `tsx`, `js`, `json`, `swift`, `kotlin`)
- File path label when showing where code goes

### Interactive Snack Examples

```jsx
<SnackInline label="Basic file read" dependencies={['expo-file-system']}>
```tsx
import * as FileSystem from 'expo-file-system';

export default function App() {
  // ...
}

Collapsible Examples

<Collapsible summary="Advanced usage with error handling">
```ts
try {
  const result = await someAsyncOperation();
} catch (error) {
  console.error('Operation failed:', error);
}

API Reference Section

End documentation pages with:

<APISection packageName="expo-file-system" apiName="FileSystem" />

This auto-generates the API reference from TSDoc comments.

Quick Reference

Do:

• Use third-person declarative ("Gets", "Returns", "Checks")
• Document behavior beyond params/returns (failures, side effects, concurrency)
• Use @platform tags for platform-specific APIs
• Include practical @example blocks
• Export types from entry points

Don't:

• Write useless descriptions ("The width" for a width property)
• Use imperative mood ("Get the value")
• Skip documentation for complex behavior
• Forget to re-export types for docs generation
• Use @link tag (not supported — use standard markdown links)
• Add @platform tags when all platforms are supported