chore: add doc generation for AI

.changeset/silly-insects-draw.md

@@ -0,0 +1,9 @@
+---
+"@effect/docgen": minor
+---
+
+- **Extracts examples from descriptions** – This can be disabled using `skip-type-checking` metadata on fenced code blocks. `@example` tags still work, but we may remove them in the future.
+- **Supports the `@throws` JSDoc tag** – Properly documents possible errors.
+- **Basic support for the `@see` JSDoc tag** – Displays only the API name and description.
+- **Adds GitHub source links** – Provides direct access to the corresponding source code.
+- **Repositions signatures** – Now moved further down, just before the source link and `@since` tag, for better readability.

.github/actions/setup/action.yml

@@ -4,7 +4,7 @@ inputs:
   node-version:
     description: The version of Node.js to install
     required: true
-    default: 20.16.0
+    default: 23.7.0
 
 runs:
   using: composite

.github/workflows/pages.yml

@@ -31,7 +31,7 @@ jobs:
           destination: ./_site
       - name: Upload pages artifact
         if: github.repository_owner == 'Effect-Ts' && github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: actions/upload-pages-artifact@v2
+        uses: actions/upload-pages-artifact@v3
 
   deploy:
     if: github.repository_owner == 'Effect-Ts' && github.event_name == 'push' && github.ref == 'refs/heads/main'
@@ -48,4 +48,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/snapshot.yml

@@ -0,0 +1,23 @@
+name: Snapshot
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  snapshot:
+    name: Snapshot
+    if: github.repository_owner == 'Effect-Ts'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        uses: ./.github/actions/setup
+      - name: Build package
+        run: pnpm build
+      - name: Create snapshot
+        id: snapshot
+        run: pnpx [email protected] publish --pnpm --comment=off

docgen.json

@@ -8,9 +8,18 @@
     "exactOptionalPropertyTypes": true,
     "moduleResolution": "Bundler",
     "target": "ES2022",
-    "lib": [
-      "ES2022",
-      "DOM"
-    ]
+    "lib": ["ES2022", "DOM"]
+  },
+  "examplesCompilerOptions": {
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "exactOptionalPropertyTypes": true,
+    "moduleResolution": "Bundler",
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "paths": {
+      "@effect/docgen": ["../../src/index.js"]
+    }
   }
 }

docs/modules/CLI.ts.md

@@ -1,15 +1,38 @@
 ---
 title: CLI.ts
-nav_order: 1
+nav_order: 2
 parent: Modules
 ---
 
-## CLI overview
+## CLI.ts overview
 
-Added in v1.0.0
+Since v0.6.0
 
 ---
 
-<h2 class="text-delta">Table of contents</h2>
+## Exports Grouped by Category
+
+- [CLI](#cli)
+  - [cli](#cli-1)
 
 ---
+
+# CLI
+
+## cli
+
+**Signature**
+
+```ts
+declare const cli: (
+  args: ReadonlyArray<string>
+) => Effect.Effect<
+  void,
+  ValidationError.ValidationError | Domain.DocgenError | PlatformError,
+  Domain.Process | CommandExecutor | CliApp.Environment
+>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/CLI.ts#L214)
+
+Since v0.6.0

docs/modules/Checker.ts.md

@@ -0,0 +1,152 @@
+---
+title: Checker.ts
+nav_order: 1
+parent: Modules
+---
+
+## Checker.ts overview
+
+Since v0.6.0
+
+---
+
+## Exports Grouped by Category
+
+- [utils](#utils)
+  - [checkClasses](#checkclasses)
+  - [checkConstants](#checkconstants)
+  - [checkExports](#checkexports)
+  - [checkFunctions](#checkfunctions)
+  - [checkInterfaces](#checkinterfaces)
+  - [checkModule](#checkmodule)
+  - [checkModules](#checkmodules)
+  - [checkNamespaces](#checknamespaces)
+  - [checkTypeAliases](#checktypealiases)
+
+---
+
+# utils
+
+## checkClasses
+
+**Signature**
+
+```ts
+declare const checkClasses: (
+  models: ReadonlyArray<Domain.Class>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration | Parser.Source>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L112)
+
+Since v0.6.0
+
+## checkConstants
+
+**Signature**
+
+```ts
+declare const checkConstants: (
+  models: ReadonlyArray<Domain.Constant>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration | Parser.Source>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L125)
+
+Since v0.6.0
+
+## checkExports
+
+**Signature**
+
+```ts
+declare const checkExports: (
+  models: ReadonlyArray<Domain.Export>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration | Parser.Source>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L185)
+
+Since v0.6.0
+
+## checkFunctions
+
+**Signature**
+
+```ts
+declare const checkFunctions: (
+  models: ReadonlyArray<Domain.Function>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration | Parser.Source>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L87)
+
+Since v0.6.0
+
+## checkInterfaces
+
+**Signature**
+
+```ts
+declare const checkInterfaces: (
+  models: ReadonlyArray<Domain.Interface>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration | Parser.Source>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L138)
+
+Since v0.6.0
+
+## checkModule
+
+**Signature**
+
+```ts
+declare const checkModule: (module: Domain.Module) => Effect.Effect<Array<string>, never, Configuration.Configuration>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L192)
+
+Since v0.6.0
+
+## checkModules
+
+**Signature**
+
+```ts
+declare const checkModules: (
+  modules: ReadonlyArray<Domain.Module>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L216)
+
+Since v0.6.0
+
+## checkNamespaces
+
+**Signature**
+
+```ts
+declare const checkNamespaces: (
+  models: ReadonlyArray<Domain.Namespace>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration | Parser.Source>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L172)
+
+Since v0.6.0
+
+## checkTypeAliases
+
+**Signature**
+
+```ts
+declare const checkTypeAliases: (
+  models: ReadonlyArray<Domain.TypeAlias>
+) => Effect.Effect<Array<string>, never, Configuration.Configuration | Parser.Source>
+```
+
+[Source](https://github.com/effect-ts/docgen/blob/main/src/Checker.ts#L151)
+
+Since v0.6.0