boxlang-docbox

DocBox — API 文档生成器

BoxLang 是一个 AI 原生软件生产力平台，用于构建、现代化改造和运行应用程序，让开发者与 AI Agent 协同工作。

概览

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。

Frames 主题（传统）：三面板框架集、左侧边栏包导航、深色模式、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"，传统三面板布局使用 "frames"
• 在同一个 DocBox 实例中添加多个策略，以便一次运行生成多种格式