システム別ドキュメント構造化の提案

[R-F-D]

各ゲームシステムに紐づくドキュメントは 現在、GameSystem派生の各クラスの下に、プレーンテキストの形で記述されています。 （ただし標準ダイスボットを除く）

これをJSON等で構造化することで 公式ドキュメント作成やオンセツール側での様々な活用が可能になると考えます。

現状のHELP_MESSAGEを見て検討したところ、以下のような構造であればうまく整理できそうです。

---

• gameSystem {object} - ゲームシステムのメタデータ。
  • id {string} - ゲームシステム識別子。クラス内にデータを置く場合は定数 ID から自動取得。
  • name {string} - ゲームシステム名。定数 NAME から自動取得。
  • sortKey {string} - ゲームシステム名の読み方。定数 SORT_KEY から自動取得。
• functions {object[]} - 個々の機能。
  • type {string} - 機能の分類。"dice" "table" "misc" のいずれか1つ。
  • name {string} - 機能名称。ドキュメントでは小見出しになる想定。
  • description {string} - 当該機能の概要。
  • formats {string[]} - 機能呼び出しフォーマット。"nDm" "*T" "Foo{目標値}" など形式は制限しない。
  • vars {object[]} - 機能呼び出しフォーマットの文中にある変数。
    • name {string} - 変数名。
    • description {string} - 変数の概要。
    • detail {string} - 変数の詳細説明。取りうる値など。
  • notices {string[]} - 機能の注釈。を使用する上で注意事項などがあれば。
  • examples {object[]} - 機能の使用例。
    • request {string} - リクエスト文字列の例。
    • response {string} - レスポンス文字列の例。

• enabledD66 {boolean} - D66ダイスの可否。変数 @enabled_d66 から自動取得。

  自動取得とあるものは、ソースコードから取得ないし実行時に動的取得が望ましい要素です。 逆に、JSON側データを主として、クラス内でこれを読み取るという形も考えられます。

とりあえずの懸念点は

• とにかく作業量が多い
• オンセツール側にも作業が発生する（従来に近いプレーンテキストを出力しても良い）
• データを別ファイルにする場合は管理の手間が増える
• データをクラス内に置く場合はRuby以外からの利用がしにくくなる

[ysakasin]

非常に魅力的、かつ活用しがいのありそうな提案ありがとうございます。

ヘルプメッセージがより構造的になるのは非常にメリットなのですが、以下のデメリットに目がいってしまって導入には否定的な印象を持っています。

• 作業量
  • BCDiceは対応しているゲームシステムが100以上ある
• 構造を決め打ちにしないといけない
  • 設計段階で項目をある程度決め打ちしないといけない
  • 項目の追加や変更があったときにオンセツールに対応のしわ寄せがいく

この方式を採用するならば、あくまで生成するプレーンテキストを最終成果物とし、ヘルプメッセージを宣言的に記述できる補助ツールとして用いるのが着地点かなと思います。ただ、この着地点だとあくまでプレーンテキストを改善するというのが結果になってしまうので、わざわざ仕組み化せずとも従来の方式で内容を充実化することでも達成できてしまいます。

R.F.D.さんがこの提案をなさった意図は、あくまでコマンドの定義そのものをオンセツールなり公式ドキュメントで生かしたいという点だと思いますが、活用は難しいのではないかと思います。特に、オンセツールがBCDice-APIを使っている場合はBCDiceのバージョンを固定できませんし、バージョンを見て挙動を変えるように促すのはあまりしたくないです。

[ysakasin]

仮に導入する場合の検討

• どこに書くか
  • lib/bcdice/game_system 以下の各Rubyコード
  • 定義を別ファイルにしたら絶対に更新を忘れられる
• 従来形式のようにプレーンテキストで吐き出す機能は必須
• Ver3で一気に対応とかは絶対に無理なので、やるなら徐々に移行

[ochaochaocha3]

@R-F-D 「個々の機能」の詳しさから、（従来のプレーンテキストとは別に）Doxygenで出力されるドキュメントのようなものが想定されているのでしょうか？

[R-F-D]

@R-F-D 「個々の機能」の詳しさから、（従来のプレーンテキストとは別に）Doxygenで出力されるドキュメントのようなものが想定されているのでしょうか？

そこまで豪勢なものではないですけど、イメージとしてはまさにそんな感じでした。