rustdoc から README.md ファイルの内容を流用する方法について。

基礎知識

rustdoc のための文書化コメントは Markdown 形式で記述される。

そして、コード共有サイト GitHub で活用されるコード全体の概要説明ファイル README.md も Markdown 形式で記述される (注: 後述の注意点のため完全な互換性はない)。

サンプル

README.md


My original crate.

# Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.

# Duis aute

Duis aute irure dolor in reprehenderit in voluptate velit esse
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
cupidatat non proident, sunt in culpa qui officia deserunt mollit
anim id est laborum.

src/lib.rs


#![doc = include_str!("../README.md")]
//! 
//! # Examples
//! ```
//! f();
//! ```

/// My original function.
pub fn f() {}

注意点

文書化コメントと README.md、それぞれの Markdown には若干の違いがある。

そのため、内容を流用する予定がある場合、書式に注意が必要になってしまう。

とは言え、共通部分も多いので流用は十分可能。なぜなら、Markdown には幾つかの方言があるが、どちらも CommonMark を採用している。また、そこからの互いの独自拡張にも同じものが多い。

独自拡張の詳細

文書化コメント: rustdoc Markdown
README.md: GFM (Github Flavored Markdown)

基本方針

文書化コメント側を基準にしておくと上手くいく場合が多い。なぜなら、README.md で使われる GFM のほうが機能が多いため、そちらの書式を基準にしてしまうと、いざ流用した時にそれが機能していないという事態が多くなってしまう。