在文档中将长表行分成多行

Question

我想记录我的箱子并在文档中包含一个表格：

//! 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 |

结果是：

我有什么选项可以在我的文档中包含长表行而不违反行长度限制？

Answer 1

HTML

正如弗朗西斯已经回答的那样，如果你想保持短线，你必须使用HTML。 rustdoc使用pulldown-cmark并且不支持你想要的东西。

包括外部文档

nightly & doc

Tracking issue: rfc 1990 - add external doc attribute to rustc。在nightly工具链的情况下，您可以启用external_doc功能并包含#[doc(include = "../some/path")]的外部Markdown文件。

有一点需要注意 - 无论在哪个模块中你将使用#[doc(include = "...")]，路径总是相对于板条箱根（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;

您可以在src/文件夹中保留单独的Markdown文档，您可以将它放在doc/等单独的文件夹中。但路径始终相对于crate根目录。

nightly & rdoc

还有rdoc编译器插件（需要nightly），它基本上做同样的事情。如何启用和使用它在项目README.md中描述。

stable

为了稳定，我会做以下事情：

• 单独的Markdown文件中的文档，
• 自定义build.rs将扫描.md文件并将其输出为.rs文件（相同的内容，只是在///或//!前面加上每一行）， 把它们放在std::env::var("OUT_DIR")文件夹中，
• 将它们包含在源代码中， 通过include!(concat!(env!("OUT_DIR"), "/main-hallo-md.rs"));。

rustfmt＆nightly

有comment_width选项（默认为80）和wrap_comments选项（默认为false）。这有助于您将评论保持在某个宽度。但我用长Markdown表格线试了一下它包裹它 - >破桌子。不要使用它。

Answer 2

使用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>::&lt;></code></td>
//!             <td>Ferris for president 🦀</td>
//!             <td>
//!                 I can't think of any
//!                 more "funny" things
//!             </td>
//!             <td>oopsie</td>
//!         </tr>
//!     </tbody>
//! </table>