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

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。rustdoc使用pulldown-cmark并且不支持您想要的内容。

包括外部文档

每晚和医生

跟踪问题：rfc 1990 - 将外部 doc 属性添加到 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 根目录。

每晚和 RDoc

还有rdoc编译器插件（requires 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 表行尝试了它，它包裹了它 -> 损坏的表。不要使用它。