3

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

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

结果是：

在此处输入图像描述

在不违反行长限制的情况下，我必须在我的文档中包含长表行的哪些选项？

4

2 回答 2

4

使用 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>
于 2019-03-24T15:23:15.393 回答
1

HTML

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

包括外部文档

每晚和医生

跟踪问题：rfc 1990 - 将外部 doc 属性添加到 rustc。在nightly工具链的情况下，您可以启用external_doc功能并将外部 Markdown 文件包含在#[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编译器插件（需要nightly），它基本上做同样的事情。如何启用和使用它在项目README.md中描述。

稳定的

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

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

rustfmt & 每晚

有comment_width选项（默认为80）和wrap_comments选项（默认为false）。这可以帮助您保持评论的宽度。但我用长的 Markdown 表格线尝试了它，它包裹了它 -> 破碎的表格。不要使用它。

于 2019-03-30T15:37:36.043 回答