rust - 如何将 Rust 模块文档保存在单独的 Markdown 文件中？

Question

Rust 书的这一部分似乎暗示可以将 Rust 文档保存在单独的 .md 文件中，但它没有说明如何将这些 .md 文件包含回来。这是如何运作的？

score 9 · Accepted Answer

将 Rust 模块文档放在单独的 Markdown 文件中的语法是：

#![doc = include_str!("path/to/some-documentation.md")]

/* content of the module */

从稳定的 Rust 1.54.0 开始支持这一点。

在从 1.50.0-nightly 到 1.53.0-nightly 的旧的 nightly 编译器上，需要一个不稳定的功能才能使上述功能可用。

#![feature(extended_key_value_attributes)]

#![doc = include_str!("path/to/some-documentation.md")]

在 nightly 编译器 1.24.0-nightly 到 1.53.0-nightly 上，以下替代语法可用，但已被删除。

#![feature(external_doc)]

#![doc(include = "path/to/some-documentation.md")]

score 2 · Accepted Answer

它没有。描述的功能的那部分rustdoc是说它可以处理单个.md文件。第三段涉及到这一点：

可以通过两种方式生成文档：从源代码和独立的 Markdown 文件。

据我所知，没有现成的方法可以将代码文档放在外部文件中。理论上可以使用程序派生宏来做到这一点，但我不知道有任何板条箱实际上可以做到这一点。

score 2 · Accepted Answer

external-doc在 stable Rust 中，您可以通过巧妙的宏来模仿不稳定的特性。

一个简单的方法是使用doc-comment crate：

#[macro_use]
extern crate doc_comment;

// If you want to test examples in your README file.
doctest!("../README.md");

// If you want to document an item:
doc_comment!(include_str!("another_file.md"), pub struct Foo {});

你可以在我的 crate SNAFU 中看到一个复杂的版本，我将它用于用户指南。

“手动”版本涉及将要记录的内容与包含的降价一起传递：

macro_rules! inner {
    ($text:expr, $($rest: tt)*) => {
        #[doc = $text]
        $($rest)*
    };
}

inner! {
    include_str!("/etc/hosts"),
    mod dummy {}
}

也可以看看：

rust - 如何将 Rust 模块文档保存在单独的 Markdown 文件中？

3 回答 3

Related

Reference