RustChinaConf 2022 大会议题回顾 ｜ Part I : Rustdoc 你可以用它做什么以及它的未来

# 创建项目
> cargo new --lib basic
# 生成文档
> cargo doc
# 使用 --open 参数直接从浏览器打开文档
> cargo doc --open 

// 使用 ignore 可以让测试忽略代码
/// ```ignore
/// fn foo() {
/// ```

// should_panic 告诉 rustdoc 代码应该正确编译，但在执行过程中会出现恐慌
// 如果代码没有恐慌，测试将失败。
/// ```should_panic
/// assert!(false);
/// ```

// no_run属性将编译代码但不运行它
// 在一些希望编译但没有运行环境的场景下可以使用它
// 也可以演示一些导致未定义行为的代码片段
/// ```no_run
/// loop {
///     println!("Hello, world");
/// }
/// ```

// compile_fail告诉rustdoc编译应该失败
// 如果它编译，那么测试将失败
/// ```compile_fail
/// let x = 5;
/// x += 2; // shouldn't compile!
/// ```


// edition2015，edition2018 和 edition2021 用于告诉rustdoc，
// 代码示例应该使用相应版本的 Rust 编译
/// Only runs on the 2018 edition.
///
/// ```edition2018
/// let result: Result<i32, ParseIntError> = try {
///     "1".parse::<i32>()?
///         + "2".parse::<i32>()?
///         + "3".parse::<i32>()?
/// };
/// ```

// 下面这几种方式都可以链接到 Bar

/// This struct is not [Bar]
pub struct Foo1;

/// This struct is also not [bar](Bar "bar")
pub struct Foo2;

/// This struct is also not [bar][b]
///
/// [b]: Bar
pub struct Foo3;

/// This struct is also not [`Bar`]
pub struct Foo4;

/// This struct *is* [`Bar`]!
pub struct Bar;

use std::sync::mpsc::Receiver;

// rustdoc 支持链接到 标准库文档中的类型

/// This is a version of [`Receiver<T>`] with support for [`std::future`].
///
/// You can obtain a [`std::future::Future`] by calling [`Self::recv()`].
pub struct AsyncReceiver<T> {
    sender: Receiver<T>
}

impl<T> AsyncReceiver<T> {
    pub async fn recv() -> T {
        unimplemented!()
    }
}

/// This is a special implementation of [positional parameters].
///
/// [positional parameters]: std::fmt#formatting-parameters
struct MySpecialFormatter;

// 可以使用 `@` 来消除同名歧义

// 指定是 结构体 Foo
/// See also: [`Foo`](struct@Foo "`Foo`")
/// This struct *is* [`Bar`]!
pub struct Bar;

// 指定是函数 Foo
/// This is different from [`Foo`](fn@Foo "`Foo`")
pub struct Foo {}

pub fn Foo() {}

#![allow(rustdoc::broken_intra_doc_links)] // allows the lint, no diagnostics will be reported
#![warn(rustdoc::broken_intra_doc_links)] // warn if there are broken intra-doc links
#![deny(rustdoc::broken_intra_doc_links)] // error if there are broken intra-doc links

/// This struct is not [Bar]
pub struct Foo1;

#[doc = " This struct is not [Bar]" ]
pub struct Foo1;

#[doc = include_str!("../../README.md")]

#[doc(alias = "TheAlias")]
pub struct SomeType;

pub struct Obj {
    inner: *mut ffi::Obj,
}

impl Obj {
    #[doc(alias = "lib_name_do_something")]
    pub fn do_something(&mut self) -> i32 {
        unsafe { ffi::lib_name_do_something(self.inner) }
    }
}