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

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标记。

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

Answer 2

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 = "...")]在哪个模块中，相对于板条根（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/等单独的文件夹中保存，等等。但是路径始终相对于板条箱根。

每晚和rdoc

还有rdoc编译器插件（需要nightly），该插件基本上可以完成相同的操作。项目README.md中介绍了如何启用和使用它。

稳定

为了稳定起见，我将执行以下操作：

• 单独的Markdown文件中的文档
• 自定义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表行尝试了它，并将它包裹起来->损坏的表。不要使用它。