在文档中将长 table 行分成多行
Break long table rows into multiple lines in documentation
我想记录我的 crate 并在文档中包含 table：
//! Demonstrating MarkDown tables.
//!
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president | I can't think of any more "funny" things | oopsie |
//!
使用 cargo doc 渲染结果：
这就是我想要的。但是，您可能已经注意到，一个源代码行很长。事实上，超过 100 个字符长。像许多 Rust 项目一样，我希望所有行的长度都在 100 个字符以下。所以我试图以某种方式打破这条线。
所有这些版本：
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president
//! I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president |
//! I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president
//! | I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president |
//! | I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president \
//! I can't think of any more "funny" things | oopsie |
结果：
我有哪些选项可以在不违反行长度限制的情况下在我的文档中包含长 table 行？
使用 HTML 标记。
//! Demonstrating HTML tables.
//!
//! <table>
//! <thead>
//! <tr>
//! <th>Foo</th>
//! <th>Bar</th>
//! <th>Baz</th>
//! <th>Quux</th>
//! </tr>
//! </thead>
//! <tbody>
//! <tr>
//! <td>Hail the turbofish <code>::<></code></td>
//! <td>Ferris for president </td>
//! <td>
//! I can't think of any
//! more "funny" things
//! </td>
//! <td>oopsie</td>
//! </tr>
//! </tbody>
//! </table>
HTML
正如 Francis 已经回答的那样，如果您想保持短线，则必须使用 HTML。 rustdoc 利用 pulldown-cmark 并且不支持您想要的内容。
包括外部文档
夜间和文档
Tracking issue: rfc 1990 - add external doc attribute to rustc。对于 nightly 工具链，您可以启用 external_doc 功能并使用 #[doc(include = "../some/path")].
包含外部 Markdown 文件
需要注意一件事 - 无论您将在哪个模块中使用 #[doc(include = "...")]，路径总是 相对于 crate 根目录（lib.rs， main.rs, ...).
示例：
.
|____Cargo.toml
|____Cargo.lock
|____doc
| |____foo-bar-bar.md
|____src
| |____main-hallo.md
| |____foo
| | |____mod.rs
| | |____bar.rs
| |____main.rs
src/main.rs:
#![feature(external_doc)]
pub mod foo;
#[doc(include = "main-hallo.md")]
pub fn hallo() {}
fn main() {}
src/foo/bar.rs:
#[doc(include = "../doc/foo-bar-bar.md")]
pub struct Bar;
您可以将单独的 Markdown 文档保存在 src/ 文件夹中，您可以将其放在单独的文件夹中，例如 doc/，等等。但是路径始终是相对于 crate root 的。
夜间和 rdoc
还有rdoc compiler plugin (requires nightly), which basically does the same thing. How to enable & use it is described in the project README.md。
stable
对于 stable，我将执行以下操作：
- 单独的 Markdown 文件中的文档，
- custom
build.rs 将扫描 .md 文件并将它们输出为 .rs 文件（相同的内容，只需在每一行前面加上 /// 或 //!),
- 将它们放在
std::env::var("OUT_DIR") 文件夹中，
- 将它们包含在您的源代码中，
- 通过
include!(concat!(env!("OUT_DIR"), "/main-hallo-md.rs"));.
rustfmt & 每晚
有 comment_width 选项（默认为 80）和 wrap_comments 选项（默认为 false）。这有助于您将注释保持在一定宽度。但是我用长的 Markdown table 行试了一下，它把它包起来了 -> 坏了 table。不要使用它。
我想记录我的 crate 并在文档中包含 table：
//! Demonstrating MarkDown tables.
//!
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president | I can't think of any more "funny" things | oopsie |
//!
使用 cargo doc 渲染结果：
这就是我想要的。但是，您可能已经注意到，一个源代码行很长。事实上，超过 100 个字符长。像许多 Rust 项目一样，我希望所有行的长度都在 100 个字符以下。所以我试图以某种方式打破这条线。
所有这些版本：
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president
//! I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president |
//! I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president
//! | I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president |
//! | I can't think of any more "funny" things | oopsie |
//! | Foo | Bar | Baz | Qux |
//! | --- | --- | --- | --- |
//! | Hail the turbofish `::<>` | Ferris for president \
//! I can't think of any more "funny" things | oopsie |
结果：
我有哪些选项可以在不违反行长度限制的情况下在我的文档中包含长 table 行？
使用 HTML 标记。
//! Demonstrating HTML tables.
//!
//! <table>
//! <thead>
//! <tr>
//! <th>Foo</th>
//! <th>Bar</th>
//! <th>Baz</th>
//! <th>Quux</th>
//! </tr>
//! </thead>
//! <tbody>
//! <tr>
//! <td>Hail the turbofish <code>::<></code></td>
//! <td>Ferris for president </td>
//! <td>
//! I can't think of any
//! more "funny" things
//! </td>
//! <td>oopsie</td>
//! </tr>
//! </tbody>
//! </table>
HTML
正如 Francis 已经回答的那样，如果您想保持短线，则必须使用 HTML。 rustdoc 利用 pulldown-cmark 并且不支持您想要的内容。
包括外部文档
夜间和文档
Tracking issue: rfc 1990 - add external doc attribute to rustc。对于 nightly 工具链，您可以启用 external_doc 功能并使用 #[doc(include = "../some/path")].
需要注意一件事 - 无论您将在哪个模块中使用 #[doc(include = "...")]，路径总是 相对于 crate 根目录（lib.rs， main.rs, ...).
示例：
.
|____Cargo.toml
|____Cargo.lock
|____doc
| |____foo-bar-bar.md
|____src
| |____main-hallo.md
| |____foo
| | |____mod.rs
| | |____bar.rs
| |____main.rs
src/main.rs:
#![feature(external_doc)]
pub mod foo;
#[doc(include = "main-hallo.md")]
pub fn hallo() {}
fn main() {}
src/foo/bar.rs:
#[doc(include = "../doc/foo-bar-bar.md")]
pub struct Bar;
您可以将单独的 Markdown 文档保存在 src/ 文件夹中，您可以将其放在单独的文件夹中，例如 doc/，等等。但是路径始终是相对于 crate root 的。
夜间和 rdoc
还有rdoc compiler plugin (requires nightly), which basically does the same thing. How to enable & use it is described in the project README.md。
stable
对于 stable，我将执行以下操作：
- 单独的 Markdown 文件中的文档，
- custom
build.rs将扫描.md文件并将它们输出为.rs文件（相同的内容，只需在每一行前面加上///或//!),- 将它们放在
std::env::var("OUT_DIR")文件夹中，
- 将它们放在
- 将它们包含在您的源代码中，
- 通过
include!(concat!(env!("OUT_DIR"), "/main-hallo-md.rs"));.
- 通过
rustfmt & 每晚
有 comment_width 选项（默认为 80）和 wrap_comments 选项（默认为 false）。这有助于您将注释保持在一定宽度。但是我用长的 Markdown table 行试了一下，它把它包起来了 -> 坏了 table。不要使用它。