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

【问题标题】：How is it possible to keep Rust module documentation in separate Markdown files?如何将 Rust 模块文档保存在单独的 Markdown 文件中？
【发布时间】：2018-02-26 00:45:34
【问题描述】：

This section of the Rust book 似乎暗示可以将 Rust 文档保存在单独的 .md 文件中，但它没有说明如何将这些 .md 文件包含回来。这是如何工作的？

【问题讨论】：

标签： rust documentation rustdoc

【解决方案1】：

将 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")]

【讨论】：

当然，令人沮丧的是，当不稳定的功能可能随时更改或消失时，很难推荐它们。
另一方面，人们需要使用不稳定的功能并提供有关它们的反馈，然后才能稳定下来。如果没有任何人使用功能，他们只会永远呆在晚上或被报废。

【解决方案2】：

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

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

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

【讨论】：

谢谢。我不认为那段说得很清楚，但事实就是如此。
**眯着眼睛转过头** 是的，我可以看到您如何将其解读为支持外部文件，特别是如果您期待该功能。考虑到这一点，我不确定在没有明确的“不支持”免责声明的情况下如何避免混淆。
也就是说，这些.md 文件只对有关板条箱的通用文档有用，而不是专门与板条箱的任何部分相关联？
@BHustus：独立的.md 文件就是这样：独立的。他们与任何板条箱没有任何关系。如果需要，您可以使用它们来撰写博客文章； rustdoc 不在乎。

【解决方案3】：

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

一个简单的方法是使用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 中看到一个复杂的版本，I use it for the user's guide。

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

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

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

另见：

【讨论】：