ruby - ルビーコードとプロジェクトのREADMEファイルのドキュメントに最適なwiki構文

Question

ルビーの世界で推奨されているrdoc、markdown、...のようなwiki構文はありますか？私は時々オープンソースコードを書きますが、コードド​​キュメントとREADMEファイルでどの構文を使用すべきかがわかりません。何が私に役立つのか、そしてなぜあなたはそれを使うのか。

Answer 1

RDoc はデフォルトのドキュメント ツールです。RDoc 構文は、Ruby ファイルおよびライブラリ内で許可されるデフォルトの構文です。

Ruby クラスの外部で、README ファイルや CHANGELOG ファイルなどのテキスト ファイルに TextTile または Markdown が使用されていることがあります。しかし、これは標準のシンタックスではないため、ファイルがどの構文で書かれているかをパーサーに伝える方法が必要です。通常、この方法はファイル拡張子です。

たとえば、GitHub はまさにこの規則に従います。.textile または .markdown 拡張子が指定されていない限り、ファイルは RDoc として解析されます。

• http://github.com/weppos/whois (.rdoc == Rdoc)
• http://github.com/rails/rails/tree/master/railties/ (拡張子なし == Rdoc、GitHub 用ではありません)
• http://github.com/technoweenie/restful-authentication/blob/master/README.textile (.textile == テキスタイル)

覚えておいてください：インラインドキュメントは常にRDocとして解析されます。

Answer 2

Github では、主に Rdoc または Textile を README ファイルの形式として使用します。Rdoc は、構文がコードに非常にうまく統合され、読みやすいため、コードの API 文書化にも非常に役立ちます。