我正在构建一个Rust库,并希望给它一些润色.在rustdoc中,我有时想在文档中链接到库的其他部分,例如fns,traits或structs.这是什么官方语法？

rustdoc允许您通过在每行上面包含doc注释来记录struct字段和枚举变体:

enum Choices {
  /// The first choice.
  First,
  /// The second choice.
  Second,
}

struct Person {
  /// The person's name.
  name: String,
  /// The person's age.
  age: u8,
}

这些将在rustdoc生成的HTML中显示出良好的格式.但是,我还没有看到任何方法为函数参数制作类似的格式良好的文档.是否有"官方"方式来记录它们,或者您只需要在函数的主要文档部分中描述它们是否自由形式？

我刚刚开始玩Rust,并试图为我编写的代码生成文档.当我发布时cargo doc,我看到了一些有点奇怪的东西.

21:53 $ cargo doc
   Compiling regex-syntax v0.2.2
   Compiling libc v0.2.2
   Compiling memchr v0.1.7
   Compiling aho-corasick v0.3.4
   Compiling regex v0.1.41
   Compiling my_project v0.0.1 (path/to/my_project)

当我打开时my_project/target/doc/my_project/index.html,我注意到所有依赖项都包含在我的文档中:

我希望这些依赖项的文档对用户隐藏,因此我的文档仅显示如何使用我的代码.

我怎样才能做到这一点？

Cargo.lock

[root]
name = "my_project"
version = "0.0.1"
dependencies = [
 "regex 0.1.41 (registry+https://github.com/rust-lang/crates.io-index)",
]

[[package]]
name = "aho-corasick"
version = "0.3.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
dependencies = [
 "memchr 0.1.7 (registry+https://github.com/rust-lang/crates.io-index)",
]

[[package]]
name = "libc"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"

[[package]]
name = "memchr" …

根据doc.rust-lang.org

\n
• cargo rustdoc
\n

\n

使用指定的自定义标志构建包的文档

\n

\n
• cargo doc
\n

\n

构建包的文档

\n

两者有什么区别？据我了解，cargo rustdoc就像cargo doc，但它允许更多 lints\xe2\x80\x94 例如：

#![deny(rustdoc::broken_intra_doc_links)]\n

它是否正确？奇怪的是，cargo rustdoc在某些情况下，它也会失败cargo doc。例如

some/folder on some-branch [$!] via  v1.60.0-nightly\n\xe2\x9d\xaf cargo doc\n    Finished dev [unoptimized + debuginfo] target(s) in 0.53s\n\nsome/folder on some-branch [$!] via  v1.60.0-nightly\n\xe2\x9d\xaf cargo rustdoc\nerror: manifest path `some/folder/Cargo.toml` is a virtual manifest, but this command requires running against an actual package …

如果您查看docs.rs上的Tokio 文档，有一个蓝色标签表示必须激活某个功能才能访问此 API：

我也想为我的板条箱启用此功能，如何做到这一点？

我在我的库的文档示例中修复错误时遇到了困难.我有像我的箱子一样的文件结构bignum

.
|-- Cargo.lock
|-- Cargo.toml
|-- examples
|   |-- dat
|   |   `-- euler_13.dat
|   |-- debug.rs
|   `-- euler_13.rs
|-- README.md
|-- src
|   |-- error.rs
|   |-- inits.rs
|   `-- lib.rs

在我的示例中,我的标题看起来像

// euler_13.rs 
extern crate bignum;
use bignum::inits::Zero;

// ...

这编译并且工作得很好,但是现在当我在我的文档中写一个例子时lib.rs,我似乎无法导入bignum::inits::Zero

//lib.rs
//...

impl BigNum {

    //...


    /// Constructs a ...
    ///
    /// # Examples
    ///
    /// ```
    /// extern crate bignum;
    /// use bignum::inits::Zero;
    ///
    /// let a = bignum::BigNum::new(Zero::zero());
    /// …

从Rust 1.6.0开始,生成的文档隐藏了每个宏模式的实现:

有没有办法隐藏Cargo生成的文档中的一些模式？

macro_rules! mc {
    // hide this entire pattern
    (@impl, $arg:expr) => { 42 + $arg };
    // but not this one
    ($arg:expr) => { mc!(@impl, $arg) };
}

有没有办法从///评论中在 doc/ 中生成单个降价文件？

多个降价文件（doc/main.md、doc/foo.md等）也很好。

我是 Rust 的新手，虽然生成的 HTML 文档很好，但我主要使用命令行，真的不想为了阅读文档而在我的终端和 Web 浏览器之间切换。这打破了流程并使我离开了区域。此外，md 很容易转换为手册页，或转换为 TeX 以用于打印或 PDF 文档。

（我已经习惯了中止与按Ctrl-Z的vim或者使用其他终端选项卡，并运行man或perldoc或pydoc等文本模式浏览器，如lynx，也不links是我不擅长的选项-导航显得笨拙，输出是对我的200多列丑如果我忘记使用该-width选项，则终端窗口不支持 javascript）

可以使用以下命令为 crate 设置favicon和rustdoc徽标：

• #![doc(html_favicon_url = "<url_to>/favicon.ico")]
• #![doc(html_logo_url = "<url_to>/logo.png")]

如此处记录的。

但是，我不想公开上传我的徽标，因此希望自动包含这些文件/target/doc并从那里引用它们。

目前，我已将相应的数据 url（base64 编码）放入这些字段中，它工作正常，但它极大地膨胀了设置这些属性的源文件。

我知道我可以在使用脚本生成文档后将图像复制到其中target/doc，然后使用相对 url 引用它们，但我想避免这种情况，以便我仍然可以使用cargo doc.

编辑

评论中设置using in--output标志的建议也不起作用，因为它会导致. 除此之外，它不适合我，因为（至少据我所知）我只能在那里给出绝对路径，而我需要一个使用图像相对路径的解决方案，因为我将这些图像存储在Cargo 根目录的子目录，以便使用 git 等轻松传输到另一个系统。rustdocrustdocflags.cargo/config.tomlerror: Option 'output' given more than once

在我的另一个问题中，我问如何仅公开公开Foo<u32>私有泛型类型 () 的具体变体 ( Foo<T>)。建议的解决方案如下：

mod internal {
    /// Private documentation of `Foo`.
    pub struct Foo<X> {
        /// Private documentation of `x`.
        pub x: X,
    }

    impl Foo<u32> {
        pub fn foo() -> u32 {
            32
        }
    }

    impl Foo<u8> {
        pub fn foo() -> u8 {
            8
        }
    }
}

/// Public documentation of `FooBar`.
pub type FooBar = internal::Foo<u32>;

这是有效的，因为公共 API 只包含FooBar，但不包含Foo。然而，从文档的角度来看，它是缺乏的。cargo doc这是for的输出FooBar：

如你看到的，

• 私有类型 …