expo-api-docs

โดย expo

เขียนความคิดเห็น TSDoc สำหรับ Expo SDK APIs ตามหลักปฏิบัติทางการ ต้องใช้เมื่อแนะนำ TypeScript APIs ใหม่ที่ผู้ใช้เห็นในแพ็กเกจ expo-* - เอกสาร…

npx skills add https://github.com/expo/expo --skill 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

TagPurposeExample
@paramParameter description@param options Configuration for the request
@return / @returnsReturn value description@return A promise fulfilled with the result
@defaultDefault value (no markdown, rendered as inline code)@default 1
@platformPlatform availability (android, ios, web, expo)@platform ios 11+
@exampleCode example (placed at bottom of description)See examples below
@deprecatedDeprecation notice (auto-formatted as warning)@deprecated Use newMethod() instead
@experimentalExperimental API label@experimental
@hidden / @internal / @privateHide from generated docs@hidden
@headerGroup methods under custom headers@header Scheduling
@needsAuditMark for security/API audit (comment, not tag)// @needsAudit
@hideTypeHide generated Type callout for constants@hideType

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

Skills เพิ่มเติมจาก expo

add-app-clip
expo
เพิ่มเป้าหมาย iOS App Clip ให้กับแอป Expo ใช้เมื่อผู้ใช้พูดถึง App Clip, AASA, apple-app-site-association, appclips, สมาร์ทแอปแบนเนอร์ หรือต้องการส่ง...
android-e2e-testing
expo
ทดสอบฟีเจอร์ Expo Router บนอีมูเลเตอร์ Android โดยใช้ ADB ใช้หลังจากที่ได้ใช้งานฟีเจอร์เนทีฟ Android หรือเมื่อต้องการตรวจสอบพฤติกรรม UI บน Android
android-jetpack-compose
expo
ใช้เมื่อสร้าง UI ของ Android ด้วย Jetpack Compose จัดการสถานะด้วย remember/mutableStateOf หรือใช้รูปแบบ UI แบบประกาศ
api-routes
expo
แนวทางสำหรับการสร้าง API routes ใน Expo Router ด้วย EAS Hosting
building-native-ui
expo
คู่มือฉบับสมบูรณ์สำหรับการสร้างแอป Expo ดั้งเดิม พร้อมการกำหนดเส้นทาง การจัดสไตล์ คอมโพเนนต์ และข้อกำหนดของแพลตฟอร์ม ครอบคลุมพื้นฐานของ Expo Router แท็บดั้งเดิม การนำทางแบบสแต็ก โมดอล และฟอร์มชีต พร้อมโครงสร้างเส้นทางโดยละเอียด รวมถึงกฎการจัดสไตล์ที่สอดคล้องกับแนวทางของ Apple Human Interface: เลย์เอาต์แบบ flexbox การจัดการพื้นที่ปลอดภัย แอนิเมชัน เงาผ่าน CSS boxShadow และรูปแบบการออกแบบที่ตอบสนอง เอกสารเกี่ยวกับไลบรารีที่ต้องการ (expo-image สำหรับ SF Symbols, expo-audio, expo-video,...
building-ui
expo
คู่มือฉบับสมบูรณ์สำหรับการสร้างแอปที่สวยงามด้วย Expo Router ครอบคลุมพื้นฐาน การจัดสไตล์ คอมโพเนนต์ การนำทาง แอนิเมชัน รูปแบบ และแท็บเนทีฟ
cicd-workflows
expo
ช่วยทำความเข้าใจและเขียนไฟล์ YAML ของ EAS workflow สำหรับโปรเจกต์ Expo ใช้ทักษะนี้เมื่อผู้ใช้ถามเกี่ยวกับ CI/CD หรือ workflow ในบริบทของ Expo หรือ EAS,…
data-fetching
expo
ใช้เมื่อกำลังดำเนินการหรือดีบักคำขอเครือข่าย การเรียก API หรือการดึงข้อมูลใดๆ ครอบคลุม fetch API, axios, React Query, SWR, การจัดการข้อผิดพลาด, การแคช…