RDoc記法の書き方(Rubyで使われるドキュメント記法)

2021年07月10日(土) Markdown

Markdownが開発者の間では有名ですが、他にも記法は存在します。今回はその中の一つ、RDocの書き方を紹介します。RDocは特にRuby開発者の中では標準的なドキュメントフォーマットであり、Rubyソースコードの中に書くのに適したドキュメント記法です。

内容はRDoc Documentationに沿ったものとなっています。

リスト

リストは * または - を使います。数字のリストは行頭に数字 + ドットを付けます。

書き方の例です。

1
- 1-1
- 1-2
- 1-3
2
* 2-1
* 2-2
* 2-3
3
1. 3-1
2. 3-2
3. 3-3

これは次のように出力されます。見やすいように整形してあります。

<p>1</p>
<ul>
<li><p>1-1</p></li>
<li><p>1-2</p></li>
<li><p>1-3</p></li>
</ul>
<p>2</p>
<ul>
<li><p>2-1</p></li>
<li><p>2-2</p></li>
<li><p>2-3</p></li>
</ul>
<p>3</p>
<ol>
<li><p>3-1</p></li>
<li><p>3-2</p></li>
<li><p>3-3</p></li>
</ol>

定義リスト

dl/dt/ddを使った定義リストです。これは2パターン用意されています。

1
[]
[]

この場合は label-listクラスが付いています。

<p>1</p>
<dl class="rdoc-list label-list">
<dt>
<dd><p></p></dd>
<dt>
<dd><p></p></dd>
</dl>

次に :: を使った書き方があります。

3
::
::

こちらは note-list クラスになります。

<p>3</p>
<dl class="rdoc-list note-list">
<dt>
<dd><p></p></dd>
<dt>
<dd><p></p></dd>
</dl>

見出し

見出しは行頭に = を付けます。h1〜h6まで、= の数で指定します。

= 1
== 2

出力されるHTMLにはアンカーが追加されています。

<h1 id="label-E8-A6-8B-E5-87-BA-E3-81-971">
1
<span>
<a href="#label-E8-A6-8B-E5-87-BA-E3-81-971">&para;</a>
<a href="#top">&uarr;</a>
</span>
</h1>
<h2 id="label-E8-A6-8B-E5-87-BA-E3-81-972">
2
<span>
<a href="#label-E8-A6-8B-E5-87-BA-E3-81-972">&para;</a>
<a href="#top">&uarr;</a>
</span>
</h2>

水平線

- を3つ以上つなげるとhrタグになります。

---

文字装飾

文字装飾は次のようになります。

RDoc 内容
*文字* bタグ
_文字_ emタグ
+文字+ ttタグ

リンク

リンクは 文字[URL] で表現します。

Web NotePM[https://notepm.jp]

HTMLは次のように出力されます。

<p>Web <a href="https://notepm.jp">NotePM</a> </p>

コメント

コメントは -- ではじまり、 ++ が書かれるまでとなります。

--
++

HTMLは次のように出力されます。

<p></p>

まとめ

RDocはRubyのソースコード中に記述するのを想定しているため、あまり記法のパターンは多くありません。その代わりクラス名やメソッドなどを自動的にドキュメント内のリンクに展開するなど、コードを読み進める上で便利な機能もあります。普段RDocを使っている方は、READMEなどもRDocにすることでメンテナンスが容易になりそうです。

おすすめの情報共有ツール

NotePM(ノートピーエム) は、ナレッジ共有に特化した社内版ウィキペディアです。検索に強く、情報を整理しやすいのが特徴です。3,000社以上に導入され、とくに『使いやすいさ・導入しやすさ』の点で高く評価されています。「ほしい情報を探すのが大変」「社内のナレッジ共有が上手くいっていない」とお悩みの方は、NotePMの無料トライアル をお試しください。

NotePMの資料請求はこちら