boxlang-docbox

DocBox — API ドキュメントジェネレーター

BoxLang は、開発者と AI エージェントが協力してアプリケーションを構築、モダナイズ、実行できる、AI ネイティブなソフトウェア開発生産性プラットフォームです。

概要

DocBox は BoxLang または CFML のソースコードを自動的に解析し、複数の出力形式で閲覧可能な API ドキュメントを生成します。JavaDoc 形式の /** ... */ コメント、クラス／プロパティ／関数のメタデータ、継承関係を読み取ります。

公開ドキュメント： https://docbox.ortusbooks.com

---

インストール

BoxLang モジュール（推奨）

# CommandBox web runtimes
box install bx-docbox

# BoxLang OS runtime
install-bx-module bx-docbox

CommandBox モジュール

box install commandbox-docbox --saveDev

CFML アプリケーション

# Install via CommandBox into your project
box install docbox --saveDev

DocBox がアプリケーションのルートにない場合は、マッピングを追加します。

// Application.bx / Application.cfc
this.mappings[ "/docbox" ] = expandPath( "./libraries/docbox" );

---

CLI の使用方法（BoxLang、5.0 で新登場）

boxlang module:docbox コマンドを使うと、最も手早くドキュメントを生成できます。

# Minimal usage
boxlang module:docbox --source=/path/to/code --mapping=myapp --output-dir=/docs

# With title and excludes
boxlang module:docbox --source=/src \
                       --mapping=myapp \
                       --output-dir=/docs \
                       --project-title="My API" \
                       --excludes="(tests|build)"

# Use the frames (traditional three-panel) theme
boxlang module:docbox --source=/src --mapping=myapp \
                       --output-dir=/docs \
                       --theme=frames

# Multiple source mappings
boxlang module:docbox --mappings:models=/app/models \
                       --mappings:handlers=/app/handlers \
                       --output-dir=/docs

# Show all available options
boxlang module:docbox --help

---

プログラムからの使用

単一のストラテジー

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "My API Documentation",
        outputDir    : expandPath( "./docs" ),
        theme        : "default"   // or "frames"
    } )
    .generate(
        source   = expandPath( "/app" ),
        mapping  = "app",
        excludes = "(tests|build)"
    )

複数のストラテジー（単一パス）

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "My API",
        outputDir    : expandPath( "/docs/html" ),
        theme        : "default"
    } )
    .addStrategy( "JSON", {
        projectTitle : "My API",
        outputDir    : expandPath( "/docs/json" )
    } )
    .addStrategy( "XMI", {
        outputFile   : expandPath( "/docs/diagram.uml" )
    } )
    .generate(
        source   = expandPath( "/app" ),
        mapping  = "app",
        excludes = "(tests|specs|build)"
    )

複数のソースディレクトリ

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "My API",
        outputDir    : expandPath( "/docs" )
    } )
    .generate(
        source = [
            { dir: expandPath( "/app/models" ),   mapping: "app.models" },
            { dir: expandPath( "/app/handlers" ),  mapping: "app.handlers" },
            { dir: expandPath( "/plugins" ),       mapping: "plugins" }
        ],
        excludes = "(tests|specs)"
    )

---

出力ストラテジー

HTML ストラテジー

閲覧可能な SPA またはフレームセット HTML サイトを生成します。

プロパティ	必須	説明
outputDir	はい	出力先の絶対パス
projectTitle	はい	ページタイトルに表示されます
projectDescription	いいえ	サブタイトル／説明文
theme	いいえ	"default"（SPA）または "frames"（フレームセット）。デフォルト："default"

デフォルトテーマ（SPA）：Alpine.js によるルーティング、リアルタイム検索、メソッドタブ（すべて／パブリック／プライベート）、ダークモード切り替え、Bootstrap 5。

フレームテーマ（従来型）：3 パネルのフレームセット、左サイドバーのパッケージナビゲーション、ダークモード、Bootstrap 5。

// Modern SPA (default)
.addStrategy( "HTML", {
    projectTitle : "My API",
    outputDir    : expandPath( "/docs" ),
    theme        : "default"
} )

// Traditional frameset
.addStrategy( "HTML", {
    projectTitle : "My API",
    outputDir    : expandPath( "/docs" ),
    theme        : "frames"
} )

JSON ストラテジー

ツールや CI との連携に使用できる、機械可読な JSON ファイルを生成します。

プロパティ	必須	説明
outputDir	はい	出力先の絶対パス
projectTitle	いいえ	overview-summary.json で使用されます

.addStrategy( "JSON", {
    projectTitle : "My API",
    outputDir    : expandPath( "/docs/json" )
} )

UML/XMI ストラテジー

UML 図ツールで使用する XMI ファイルを生成します。

プロパティ	必須	説明
outputFile	はい	出力先の .uml／.xmi ファイルの絶対パス

.addStrategy( "XMI", {
    outputFile : expandPath( "/docs/diagram.uml" )
} )

CommandBox ストラテジー

CommandBox 互換のコマンドドキュメントを生成します。

.addStrategy( "CommandBox", {
    outputDir : expandPath( "/commandbox-docs" )
} )

---

除外パターン

excludes パラメーターは、各クラス名とパスに対して評価される正規表現です。一致するクラスはスキップされます。

// Skip tests and build output
excludes = "(tests|specs|build)"

// Skip specific packages
excludes = "(com\.example\.internal|legacy)"

// Skip multiple patterns
excludes = "(tests|mocks|stubs|helpers)"

---

カスタム出力ストラテジー

AbstractTemplateStrategy（IStrategy を実装）を拡張して、独自の出力形式を作成できます。

/**
 * Markdown documentation strategy for DocBox.
 */
component extends="docbox.strategy.AbstractTemplateStrategy" {

    /**
     * @param metadata  Query with columns: package, name, metadata, type, extends, implements
     */
    IStrategy function run( required query metadata ) {
        var outputDir = variables.properties.outputDir

        ensureDirectory( outputDir )

        for ( var row in arguments.metadata ) {
            var mdContent = buildMarkdown( row.metadata )
            writeTemplate(
                path     = outputDir & "/" & row.name & ".md",
                template = mdContent
            )
        }

        return this
    }

    private string function buildMarkdown( required struct meta ) {
        return "# #meta.name#" & char( 10 ) & meta.hint
    }

}

登録して使用します。

new docbox.DocBox()
    .addStrategy( "docbox.strategy.MarkdownStrategy", {
        outputDir : expandPath( "/docs/markdown" )
    } )
    .generate( source = expandPath( "/app" ), mapping = "app" )

---

後方互換性

完全なクラスパスまたは単一のコンストラクターストラテジーを指定する方法も、引き続き使用できます。

// Full class path
variables.docbox = new docbox.DocBox(
    strategy   = "docbox.strategy.uml2tools.XMIStrategy",
    properties = { outputFile : expandPath( "/docs/diagram.uml" ) }
)

// Or short alias on addStrategy
docbox.addStrategy( "docbox.strategy.api.HTMLAPIStrategy", { ... } )

---

CI/CD との連携（GitHub Actions）

- name: Generate API docs
  run: |
    boxlang module:docbox \
      --source=${{ github.workspace }}/src \
      --mapping=myapp \
      --output-dir=${{ github.workspace }}/docs \
      --project-title="My API" \
      --excludes="(tests|build)"

- name: Upload docs artifact
  uses: actions/upload-artifact@v4
  with:
    name: api-docs
    path: docs/

---

チェックリスト

• DocBox がインストール済み：box install bx-docbox または install-bx-module bx-docbox
• すべてのパブリック関数に /** ... */ のドキュメントコメントがある（code-documenter スキルを参照）
• array／struct／any の戻り値および引数の型に @doc.type が追加されている
• excludes の正規表現でテスト、ビルド出力、内部パッケージが対象になっている
• outputDir が絶対パスになっている（expandPath() を使用）
• テーマを選択済み：SPA には "default"、従来型の 3 パネルレイアウトには "frames"
• 単一パスで複数形式を出力するには、1 つの DocBox インスタンスに複数のストラテジーを追加する