Zenn
📝

Godot 4.0のドキュメンテーション機能を試してみる

2022/09/17に公開
ゲーム開発
gamedev
Godot
gdscript
ゲームエンジン
tech

概説

フリーのゲーム開発エンジンGodot Engineのバージョン4.0から、ユーザが書いたコードのドキュメントを生成してくれる、ドキュメンテーション機能（Documentation Comments）が使えるようになりました。

この記事では、実際のコードを示しつつドキュメンテーション機能を試してみます。

もう自分のコードで迷子にならない

自分の書いたコードを数日空けて見てみると、迷子になる。これはコーディングしたことがある人ならば、誰しもが経験することだと思います。

Godot 4.0からはその心配や負担が少し軽減されます。コーディングの際に指定されたフォーマットでコメントを書くことで、ドキュメンテーション機能が自動的に自分のコードの説明書を生成してくれます。

早速書いてみる

ドキュメンテーション用のコメントの書き方は簡単です。

注意点は3個。

  1. 通常のコメントと違い、文頭の#を2個連続で書きます。
  2. コメントを書く位置によって、コメントの役割やドキュメンテーションの挙動が変わります。
  3. 一部のBBCodeが使えます。

ここからは実際にコード（コメント）を書いてみましょう。

クラス/スクリプトの説明を書いてみる

メソッドやプロパティの宣言の前に書かれたコメントは、クラス/スクリプトの概要になります。

クラスの説明を生成するためのコメント
extends Node

class_name SampleClass

## SampleClassの概要
##
## SampleClassの詳細
##
## @tutorial:            http://example.com

クラスの宣言後に続く5行が、実装したクラスそのものを説明するためのコメントです[1]。最初の1行がクラスの概要、3行目がクラスの詳細で、最後の行はオンラインドキュメントへのリンクとなります[2]。

百聞は一見しかずです。このコードで生成されたドキュメントを見てみましょう。


生成されたドキュメント。ちゃんと継承関係やクラス名、コメントに書いた内容が反映されていることがわかります。

クラスじゃなくてもOK

因みに、クラスを宣言していないスクリプトでも、ドキュメントは生成されます。試しに、先程のコードからクラス名の宣言部分を取り除いてみましょう。コードと結果を続けて示します。

new_script.gd
extends Node

## SampleClassの概要
##
## SampleClassの詳細
##
## @tutorial:            http://example.com


クラス名のところが、スクリプトのファイル名になっています。

プロパティの説明を書いてみる

次はプロパティ/変数の説明を書いてみます。プロパティは、宣言する前の行にコメントを書きます。

プロパティの説明
## この変数には何を代入してもいいです
var sample_variable

## この変数にはboolしか代入できません
var sample_variable_bool:bool

# この変数にはintしか代入できません
@export @onready var sample_variable_int := 51

上記のコードでは、3種類のプロパティを宣言しています。3つ目のプロパティは、コメント文頭の#が一つになっていることに注意してください。これはドキュメンテーション用ではない、通常のコメントです。

ドキュメントには以下のように反映されます。

通常のコメントしか書かれていなかったsample_variable_intには、「説明文がないよ」という注釈がついています。また、初期値が設定されているプロパティは初期値が併記されます。

メソッドの説明を書いてみる

続いてメソッド/関数の説明を書いてみましょう。メソッドもプロパティと同じく、宣言前にコメントを書きます。

以下のコードでは、_ready()と、何の役割もないメソッドを2種類用意しました。

メソッドの説明
# _readyには通常のコメントしか書いていません。
func _ready():
    return


## このメソッドは、開始直後に[code]return[/code]があるため、[b]何も起こりません[/b]。
##
func sample_function(i:int):
    return


## このメソッドも、開始直後に[code]return[/code]があるため、[b]何も起こりません[/b]。[br]
## 引数のデフォルトの値と、返り値の型を指定しているのが上のメソッドとの違いです。
func sample_function_two(i:int = 0) -> void:
    return

先ほどとは違って、コメントの中に見慣れないタグが挿入されていますね。これはBBCodeといって、テキストの装飾をするためのタグです。例えば、[b][/b]タグに囲まれた文字列は太字になります。

また_ready()の前のコメントは、#が1個しか書かれていないことに注意してください。ドキュメンテーション用ではない、通常のコメントの書き方ですね。

上記のコードで、どういうドキュメントが生成されるのかをみてみましょう。

通常のコメントしか書かれていない_ready()はドキュメントには表示されていません。メソッドの場合はドキュメンテーション用のコメントがないと、ドキュメント生成の際に無視されるようです。また、BBCodeによってテキストがちゃんと装飾されていることもわかります[3]。

そしてsample_function_two()で設定した返り値の型や引数の初期値が、ドキュメントにもきちんと反映されていることがわかります。

ドキュメントで使えるBBCode

ドキュメンテーションで使えるBBCodeは一部制限されています。4.0 beta1時点で試した範囲で使えるタグを以下に示します。

ドキュメンテーションで使えるBBCode （Godot4.0 beta1時点）

文字装飾

以下の文字装飾タグが使えました。

  • b : 太字
  • i : 斜体
  • u : 下線
  • s : 打ち消し線
  • center : 文字の中央寄せ
  • color : 文字色の変更 → 例:[color=tomato]テキスト[/color]
  • br : 改行
  • url : リンクの挿入 → 例: [url]http://example.com[/url]

ドキュメンテーション用

ドキュメンテーション用のタグには以下のものが用意されています。

  • Class : 任意のクラスへのリンク
    → 例：[Node2D]
  • method : 任意のメソッドへのリンク
    → 例：[method _ready] [method Node._ready]
  • member : 任意のメンバ（変数）へのリンク
    → 例:[member position] [member Node2D.scale]
  • signal : 任意のシグナルへのリンク
    → 例：[signal button_up]　[signal Control.button_up]
  • kbd : キーボードやマウスのショートカットの表示
  • code : 等幅書体でコードを表示する
  • codeblock : 複数行にわたるコードブロックの表示

補足・使えないタグなど

  • 私の環境では、iはアルファベットにのみ適応され、日本語は斜体になりませんでした。
  • centerは使えますが、left right fillは使えません。
  • table cell ul ol bgcolor lb rb indentなども使えません。

詳細は公式のドキュメントをチェックしてみてください。

おわり

以上が、Godot 4.0から実装されたドキュメンテーション機能のざっくりとした解説となります。

この記事で触れたプロパティ、メソッドの他にも、シグナルや内部クラス、列挙型にも説明をつけることができます[4]。公式のドキュメントを確認しながら、ぜひ試してみてください。

この記事が公開された2022年9月17日時点のGodotのバージョンは4.0 beta1です。今後仕様や挙動が微妙に変わる可能性もありますので、ご注意ください。

脚注

  1. 公式のドキュメントでは、クラス宣言の前にコメントがありますが、クラス宣言の後でもドキュメントは問題なく生成されます。 ↩︎

  2. 個人開発などではオンラインドキュメントを用意することはあまりないと思いますが、チーム開発でwikiなどを活用している場合には、外部リンクが書けるのは便利ですね。注意点としては、file://***のようなローカルのURLには対応していないことです。仮にローカルのURLを入力しても、クリックに反応しません。ちょっと残念。 ↩︎

  3. [br]によって改行されると、それ以降の行は1文字分のインデントが挿入されるので注意。Godot 3.5のドキュメントにはない挙動です。バグなのか、仕様なのか、環境依存の問題なのかは今のところ不明です。 ↩︎

  4. 内部クラスはGodot 4.0 beta1時点では動作確認できませんでした。 ↩︎

Discussion