DocBox APIリファレンス
DocBox APIリファレンス
bxSites docbox は BoxLang/CFML のクラスを、テーマが適用された検索可能な
APIリファレンスとして自分のサイト内に生成します。Gradle
プラグインと Maven プラグインが Java プロジェクトに提供
している Javadoc ジェネレーターの、BoxLang 版にあたります。
BoxLang の解析自体は行いません。その仕事は
DocBox がすでに十分にこなしているため、
ここでは DocBox 自身の JSON ストラテジーを実行し、その結果を通常の Markdown
ページへ変換します。ページはコンテンツディレクトリに他のページと同じように
配置されるので、次の build がテーマを適用し、検索インデックスに登録し、
手書きのページと同じように配信します。
前提条件
BoxLang ランタイムに bx-docbox モジュールがインストールされている必要が
あります。
# OSバイナリ
install-bx-module bx-docbox
# CommandBox
box install bx-docbox
インストールされていない場合、スタックトレースではなく対処方法を示す メッセージで終了します。
クイックスタート
bxSites docbox
bxSites build
設定が一切なくても、docbox はプロジェクトに実際に存在する慣例的な BoxLang
ソースフォルダー（models、handlers、bifs、components、
interceptors）を対象にし、docs/api/docbox/ 以下にページを書き出します。
設定
すべて省略可能です。完全なスキーマは
docbox を参照してください。
docbox:
projectTitle: "My API"
mappings:
models: models
bifs: bifs
excludes: "tests|build"
pagePathPrefix: api/docbox
tags: [ api, docbox ]
{
"docbox": {
"projectTitle": "My API",
"mappings": { "models": "models", "bifs": "bifs" },
"excludes": "tests|build",
"pagePathPrefix": "api/docbox",
"tags": [ "api", "docbox" ]
}
}
[docbox]
projectTitle = "My API"
excludes = "tests|build"
pagePathPrefix = "api/docbox"
tags = [ "api", "docbox" ]
[docbox.mappings]
models = "models"
bifs = "bifs"
各キーには、その実行だけ上書きするフラグがあります。
bxSites docbox --mappings:models=models --projectTitle="My API" \
--pagePathPrefix=api/classes --tags=api,classes --excludes=tests
--jsonDir=<パス> を渡すと、DocBox の JSON 出力を破棄せずに残します。
生成されるもの
ページは3種類です。全体のインデックス、パッケージごとのインデックス、 そしてクラスごとのページです。
docs/api/docbox/
├── index.md # すべてのパッケージとクラス
├── models/
│ ├── index.md # このパッケージのクラス
│ ├── UserService.md
│ └── security/
│ ├── index.md
│ └── Auth.md
クラスページには、そのクラスの docblock、宣言された property ブロック、
そしてアクセス修飾子ごとにまとめられた関数（コンストラクター、public、
package、private の順）が並び、それぞれ完全なシグネチャ、説明、パラメーター
表、@return のテキストを備えます。メンバーは Javadoc ページと同じ
Alpine.js のフィルターツールバーの中に置かれるため、長いクラスでも見通しが
保たれます。
ナビゲーションへの組み込み
生成されたページは通常のコンテンツなので、ディレクトリ自動ナビゲーションに
そのまま現れます。意図した場所に置きたい場合は、自分の
nav にインデックスを指定します。
nav:
- title: リファレンス
children:
- api/docbox/index.md
{
"nav": [
{ "title": "リファレンス", "children": [ "api/docbox/index.md" ] }
]
}
[[nav]]
title = "リファレンス"
children = [ "api/docbox/index.md" ]
意図的に行わないこと
- クラス間のリンクは張りません。
extends/implementsの対象や シグネチャに現れる型は、そのクラスに生成ページがあってもインラインコード として表示されます。 - 継承したメンバーは扱いません。 DocBox 自身の JSON 出力と同じく、その クラスが自ら宣言したものだけです。
- ナビゲーションの自動配線は行いません。 ページは
pagePathPrefixの 下に置かれ、配置は利用者が決めます。
メタデータの出どころ
DocBox の JSON ストラテジーは、クラスの名前・パッケージ・種別・extends・
関数をシリアライズしますが、宣言された property ブロック、実装している
インターフェース、クラスレベルのアノテーション、関数ごとの @return
テキストは含めません。この4つは BoxLang のリファレンスでは重要で、とくに
プロパティは accessors のフィールドと WireBox の inject をすべて担って
います。そのため bx-sites は、DocBox 自身が使ったのと同じクラスメタデータ
からこれらを読み直し、レンダリング前に統合します。二重に解析することは
ありません。
Gradle や Maven から
どちらのビルドプラグインもこのジェネレーターを提供しています。BoxLang/CFML のクラスを含む JVM プロジェクト向けです。 Gradleプラグイン と Mavenプラグイン を参照してくださ い。
ColdBox アプリケーションのドキュメント化は別の verb です。 ColdBoxアプリケーション を参照してください。