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

おすすめの情報共有ツール「NotePM」

NotePM

NotePM（ノートピーエム） は、Webで簡単にマニュアル作成できて、強力な検索機能でほしい情報をすぐに見つけられるサービスです。さまざまな業界業種に導入されている人気サービスで、大手IT製品レビューサイトでは、とくに『使いやすいさ・導入しやすさ』を高く評価されています。

NotePMの特徴

マニュアル作成、バージョン管理、社外メンバー共有
強力な検索機能。PDFやExcelの中身も全文検索
社内FAQ・質問箱・社内ポータルとしても活用できる
銀行、大学も導入している高度なセキュリティ。安全に情報共有できる

URL: https://notepm.jp/

NotePMについて詳しく見る＞