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

Question

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

Answer 1

没有。描述 rustdoc 功能的那一节说它可以处理单个 .md 文件。第三段讲到这个：

Documentation can be generated in two ways: from source code, and from standalone Markdown files.

据我所知，目前还没有将代码文档放入外部文件的方法。理论上可以使用程序派生宏来执行此操作，但我不知道是否有任何板条箱实际执行此操作。

Answer 2

将 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 的旧版夜间编译器上，需要一个不稳定的功能才能使用上述功能。

#![feature(extended_key_value_attributes)]

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

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

#![feature(external_doc)]

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

Answer 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 {});

你可以在我的箱子 SNAFU 中看到这个的复杂版本，其中 I use it for the user's guide。

"by-hand" 版本涉及传递要记录的内容以及包含的 markdown：

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

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

另请参阅：

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

How is it possible to keep Rust module documentation in separate Markdown files?

documentation

rust

rustdoc