boxlang-code-documenter

BoxLang 代码文档编写

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

概述

BoxLang 支持 Javadoc 风格的文档注释。为类、函数和参数编写文档，可以支持 IDE 工具、自动生成 API 文档，也能为未来的维护者提供内联规范。

---

注释样式

BoxLang 支持三种注释样式：

// Single-line comment

/* Multi-line
   comment */

/**
 * Documentation comment (Javadoc-style)
 * Used for classes, functions, and components.
 */

---

类文档

将文档注释放在 class 关键字正上方：

/**
 * UserService handles all user lifecycle operations including creation,
 * authentication, profile management, and deactivation.
 *
 * @author Jane Smith
 * @since 2.0.0
 * @see UserRepository
 */
class accessors="true" {

    property name="userRepo"  inject="UserRepository"
    property name="emailSvc"  inject="EmailService"

}

---

函数文档

为每个公共函数编写文档。将注释放在函数正上方：

/**
 * Retrieves a user by their unique identifier.
 *
 * Returns `null` if no user matching `id` is found.
 * Throws `UserNotFoundException` if `throwOnMissing` is true.
 *
 * @param  id              The unique numeric ID of the user to retrieve.
 * @param  throwOnMissing  When true, throws instead of returning null. Default: false.
 *
 * @return                 A Struct containing user data, or null.
 *
 * @throws UserNotFoundException  When throwOnMissing=true and user does not exist.
 *
 * @example
 * var user = userService.getById( 42 )
 * if ( !isNull( user ) ) {
 *     println( user.name )
 * }
 */
struct function getById(
    required numeric id,
    boolean throwOnMissing = false
) {
    var user = variables.userRepo.find( arguments.id )

    if ( isNull( user ) && arguments.throwOnMissing ) {
        throw( type="UserNotFoundException", message="User #arguments.id# not found" )
    }

    return user
}

---

核心块标签

标签	用途	示例
@param name	记录参数	@param userId The user's ID.
@return	记录返回值	@return A Struct of user data.
@throws ExType	记录抛出的异常	@throws AuthException When token invalid.
@example	提供用法示例	见上文
@since version	添加时间	@since 1.5.0
@version	组件／函数版本	@version 2.1.0
@deprecated	标记为弃用	@deprecated Use getUserV2() instead.
@see RefName	交叉引用（DocBox：尚未实现）	@see UserRepository
@author name	文件／函数作者	@author John Doe
@{anything}	自定义元数据 — DocBox 会记录任意块标签和值	@license MIT

---

参数子注解

DocBox 支持点号表示法，可为特定参数添加额外元数据。 使用 @argName.tagName value 为已记录的参数添加属性：

/**
 * Get Java FileInputStream for resource bundle.
 *
 * @rbFilePath       Path + filename for resource, including locale + .properties
 * @rbFilePath.deprecated  true
 *
 * @return java.io.FileInputStream
 * @throws ResourceBundle.InvalidBundlePath
 */
public function getResourceFileInputStream( required string rbFilePath ) {
}

---

@doc.type — 泛型类型注解

当声明类型为 array、struct 或 any 时，使用 @doc.type 为返回值和参数指定泛型类型。DocBox 会将它们渲染为带类型的泛型。

返回类型泛型

/**
 * Gets all active users.
 *
 * @return Array of User objects
 * @doc.type Array<User>
 */
public array function getActiveUsers() { }

/**
 * Gets user preferences as a configuration map.
 *
 * @return Struct mapping setting names to values
 * @doc.type Struct<String,Any>
 */
public struct function getUserPreferences() { }

参数类型泛型

/**
 * Processes a batch of user records.
 *
 * @users  Array of User objects to process
 * @users.doc.type Array<User>
 */
public void function processBatch( required array users ) { }

/**
 * Updates user settings.
 *
 * @settings  Map of setting names to their values
 * @settings.doc.type Struct<String,Any>
 */
public void function updateSettings( required struct settings ) { }

内联泛型注解（BoxLang）

// Return type inline
public array function getUsers() doc.type="Array<User>" { }

// Parameter inline
public void function setCache(
    required struct cache doc.type="String,Any"
) { }

复杂／嵌套泛型

/**
 * Gets a map of user IDs to their roles.
 *
 * @doc.type Struct<Numeric,Array<String>>
 */
public struct function getUserRoles() { }

---

属性文档

为类属性编写文档，尤其是公共 API 类中的属性：

class accessors="true" {

    /** The user's unique identifier. Read-only after creation. */
    property name="id" type="numeric" setter="false"

    /** The user's display name. Maximum 100 characters. */
    property name="displayName" type="string"

    /**
     * The user's account status.
     * Valid values: "active", "suspended", "pending", "deleted"
     */
    property name="status" type="string" default="pending"

    /** ISO 8601 timestamp of when this account was created. */
    property name="createdAt" type="date" setter="false"

}

---

完整的类文档示例

/**
 * OrderProcessor orchestrates the end-to-end order fulfillment workflow.
 *
 * Responsibilities:
 * - Validates order items and quantities
 * - Reserves inventory
 * - Processes payment
 * - Triggers fulfillment notifications
 *
 * Usage:
 * ```
 * var processor = new OrderProcessor( paymentGateway, inventoryService )
 * var result    = processor.process( order )
 * ```
 *
 * @author  Ortus Solutions
 * @since   3.0.0
 * @see     PaymentGateway
 * @see     InventoryService
 */
class {

    /** @param paymentGateway  Payment processing implementation. */
    /** @param inventoryService  Inventory management implementation. */
    function init(
        required PaymentGateway paymentGateway,
        required InventoryService inventoryService
    ) {
        variables.paymentGateway  = arguments.paymentGateway
        variables.inventoryService = arguments.inventoryService
        return this
    }

    /**
     * Processes a complete order from validation through payment.
     *
     * @param  order  A Struct containing items (Array), customerId (numeric), and shippingAddress (Struct).
     *
     * @return  A Struct with keys: success (boolean), orderId (numeric), message (string).
     *
     * @throws ValidationException  When the order structure is invalid.
     * @throws PaymentException     When payment processing fails.
     * @throws InventoryException   When items are out of stock.
     *
     * @example
     * var result = orderProcessor.process({
     *     customerId:      42,
     *     items:           [ { productId: 1, qty: 2 } ],
     *     shippingAddress: { street: "123 Main St", city: "Portland" }
     * })
     * if ( result.success ) {
     *     println( "Order #result.orderId# confirmed!" )
     * }
     */
    struct function process( required struct order ) {
        validateOrder( arguments.order )
        reserveInventory( arguments.order.items )
        var paymentResult = variables.paymentGateway.charge( arguments.order )
        return {
            success: true,
            orderId: paymentResult.transactionId,
            message: "Order confirmed"
        }
    }

    /**
     * Validates order structure and item availability.
     *
     * @param  order  The order struct to validate.
     *
     * @throws ValidationException  When order is missing required fields.
     *
     * @access private
     */
    private void function validateOrder( required struct order ) {
        if ( !structKeyExists( arguments.order, "customerId" ) ) {
            throw( type="ValidationException", message="customerId is required" )
        }
        if ( !structKeyExists( arguments.order, "items" ) || arguments.order.items.isEmpty() ) {
            throw( type="ValidationException", message="Order must contain at least one item" )
        }
    }

}

---

脚本文件文档

对于 .bxs 脚本文件，在文件顶部记录用途和用法：

/**
 * generateReport.bxs
 *
 * Generates a monthly sales summary report and saves it to /reports/.
 *
 * Usage:
 *   boxlang generateReport.bxs [--month=YYYY-MM] [--output=/path/to/output]
 *
 * Arguments:
 *   --month   Month to report on (default: previous month). Format: YYYY-MM
 *   --output  Output directory (default: /var/reports/)
 *
 * @author   Ortus Solutions
 * @requires bx-pdf module for PDF export
 */

var month  = arguments[1] ?: dateFormat( dateAdd( "m", -1, now() ), "yyyy-mm" )
var output = arguments[2] ?: "/var/reports/"

// ... script logic

---

模板文件文档

对于 .bxm 模板，添加简短的注释头：

<bx:output>
<div class="profile">
    <h1>#encodeForHTML( user.name )#</h1>
</div>
</bx:output>

---

文档完整性检查清单

对于每个公共函数，请确保文档注释包含：

• 单行摘要（注释的第一行）
• 如果行为不明显，则提供扩展说明
• 为每个参数添加 @param（名称及其用途）
• 当返回值或参数类型为 array、struct 或 any 时添加 @doc.type
• 添加 @return，说明返回内容（类型及结构）
• 为所有可能逃逸的异常类型添加 @throws
• 为任何非平凡函数添加 @example
• 为 API 版本控制添加 @since
• 为弃用函数添加 @deprecated 和替代方案说明

DocBox 集成： 按照这些约定编写的所有文档注释，都会由 DocBox 自动解析，用于生成 HTML、JSON 和 UML API 文档。运行 boxlang module:docbox --source=/src --mapping=myapp --output-dir=/docs，即可根据带注释的代码生成文档。