* 公式情報

[1] [CITE@en[comments - Documentation for Ruby 3.5]], [TIME[2025-11-01T13:20:22.000Z]], [TIME[2025-11-04T15:07:59.697Z]] <https://docs.ruby-lang.org/en/master/syntax/comments_rdoc.html#label-Magic+Comments>

* 構文

[2] 
[CODE[#]] から始まる[[行内注釈]]に、
名前と値を [CODE[:]] で区切って記述するようです。
[SRC[>>1]]

[3] 
例示では [CODE[#]] の後や [CODE[:]] の後には [CODE[ ]] が1つ置かれています。
[SRC[>>1]]
どの程度自由度があるのかドキュメント上は明らかではありません。

[4] 
[CODE[-*-]] 構文を使うと名前と値の組を1つ[[以上]]まとめて[[行内注釈]]に入れることができます。
[SRC[>>1]]
[SEE[ [[-*-]] ]]

[5] 
[DFN[top-level magic comment]] [SRC[>>1]] とそうでないものがあるようです。
ドキュメント上それらの位置付けは明確ではありませんが、
全体に適用される[[指令]]と[[ブロック]]内に適用される[[指令]]の区別であるようです。

[6] 
[CODE[#]] の前に[[文字]]を書けるのか、ドキュメント上は明らかではありません。
ドキュメントでは[[ブロック]]内に適用される[[指令]]は[[インデント]]されて示されています 
[SRC[>>1]] が、どの程度自由度があるのかドキュメント上は明らかではありません。

[7] 
[[top-level magic comment]] は[[ファイル]]の最初の comment section
に出現しなければならないとされます。 [SRC[>>1]] comment section
とは何を言うのか明確ではありません。

[8] 
ドキュメントの [CODE[encoding]] [[指令]]の説明において、
[[top-level magic comment]] は最初の[[行]]か、 [[shebang]]
の次の[[行]]になければならないとあります。 [SRC[>>1]]
ドキュメント上明瞭ではありませんが、 [CODE[encoding]] [[指令]]かつ
[[top-level magic comment]] である場合の規定なのでしょうか。
([[top-level magic comment]] でない[[魔法注釈]]として [CODE[encoding]]
が使えるものなのかもよくわかりませんが。)

;; [13] この辺の説明の不明瞭さは、
おそらく最初に [CODE[encoding:]] の[[魔法注釈]]が導入されたようで、
その後他の[[指令]]が追加されたと思われ、
その過程でドキュメントを整理しないで書き足したために見えます。

* 処理

[9] 
名前と値の組は[[指令]]の名前と値と解釈されます。 [SRC[>>1]]

[10] 
[[指令]]によってはドキュメント上、その配置された[[行]]の続きに適用されることが明言されているものもあります。
明記がないものがどうなのか、複数指定することはできるのか、などドキュメント上明らかでないことが多いです。

* 指令

[11] 
[RUBYB[[[指令]]][directive]]がいくつかあります。 [SRC[>>1]]

[12] 
[CODE[encoding]] [[指令]]は、 [CODE[coding]] とも書くことができ、
[[文字コード]]を指定します。
構文を注意して選べば、
[CITE[Emacs]]
と
[[Ruby]]
の両方に[[ファイル]]の[[文字コードの指定]]と認識させられます。
[SEE[ [CODE[-*- coding -*-]] ]]







* 関連

[SEE[ [[charset sniffing]] ]]

[SEE[ [[コメントの中身が意味を持ってしまう]] ]]

* メモ