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

こんにちは。マニュアル作成・ナレッジ共有ツール「NotePM」ブログ編集局です。

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

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

<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にすることでメンテナンスが容易になりそうです。

【ebook】失敗しない社内wiki構築ガイドライン