boxlang-code-documenter

BoxLang コードドキュメント作成ガイド

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

概要

BoxLang は Javadoc スタイルのドキュメントコメントに対応しています。クラス、 関数、引数を文書化することで、IDE のツール機能や API ドキュメントの自動生成が可能になり、 将来のメンテナー向けのインライン仕様としても役立ちます。

---

コメントスタイル

BoxLang は 3 種類のコメントスタイルに対応しています。

// 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>

---

ドキュメントの網羅性チェックリスト

すべてのパブリック関数について、ドキュメントコメントに以下が含まれていることを確認します。

• 1 行の要約（コメントの 1 行目）
• 動作が自明でない場合は、詳しい説明
• すべての引数に対する @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 を実行します。