rust生成html文档

在docs.rs看到的文档基本都是由这种方式生成的
https://docs.rs/

1、Rust原生生成

如果你写的是lib crate，可以用以下命令生成文档

rustdoc src/lib.rs

• –crate-name docsname 设置包名

文档会生成在target\doc\位置

为Markdown文件生成文档

rustdoc README.md

README.md

# 好不好玩

# 太好玩了

执行命令rustdoc README.md会在根目录的doc文件夹生成文档README.html

2、Cargo生成（推荐）

cargo 内置了rustdoc，执行以下命令生成文档，默认将当前crate及其所有依赖的crate文档加进来

cargo doc

• –open 用默认浏览器打开文档，后面指定文件名
• –no-deps 不为依赖构建文档
• –document-private-items 文档中包含非公共部分，如果是lib crate默认启用
• –manifest-path 默认根据Cargo.toml的清单，通过该参数可以指定为某个清单生成文档
• –workspace cargo.toml中所有的成员
• –no-default-features 排除指定了默认features的功能
• –exclude 排除指定包
• –verbose 启用更加详细的输出
• –quiet 不输出日志信息
• –crate-name
• -o 指定文档输出的位置
• -L 帮助 rustdoc 找到代码的依赖，如果项目有依赖，也会生成依赖的文档

语法规范

文档注释一般用于告诉他人提供了哪些API

1、//! outer文档

通常在root crate比如src/lib.rs标记，描述crate的用途

• 每个文件只能在开头描述

在interface\src\lib.rs这个lib crate中

//! 应用程序的入口点，用于启动应用程序
pub mod api{
    pub mod api;
}
/// 为什么要多加一层apapter？
/// CQRS职责分离，这里的目的是为了将业务逻辑和HTTP请求处理解耦，使应用程序的核心逻辑更加清晰，易于测试和维护
/// 将从业务逻辑层获取的数据转换为适合接口（例如 HTTP 响应）的格式
/// 只关注如何与外部进行交互，而不涉及具体的业务逻辑的实现细节
pub mod adapter{
    pub mod handler;
}
/// 公共响应
pub mod common{
    pub mod response;
}
/// 路由
pub mod routers{
    pub mod user_routes;
    pub mod order_route;
}

cargo doc生成

注意要在当前项目根目录执行

2、/// inner文档

在结构体、函数、实现、函数内部任何你想标记的地方，整个程序细节描述，比如告诉别人函数应该怎么用

• 支持Markdown语法
• # Examples 标记一个标题，标题名随便起
  • # Panics 标记可能发生panics的函数
  • # Errors 标记可能返回错误的函数，描述可能导致错误的条件等信息
  • # Safety 标记可能有安全问题的函数，描述函数为什么不安全

use interface::api::api::{self};
/// 这里是main函数
/// # Example 
/// ```
/// 行不行啊
/// ```
fn main() {
    let start_err = api::start();
    println!("{:?}", start_err);
}

cargo doc生成

如果你使用了多个模块，使用pub关键字可以将子模块的文档加入

注意区分model(模块)和crate，每个lib crate中创建的文件并定义了mod的才是模块

cargo doc --no-deps生成文档

父项目cargo.toml配置

# 工作区依赖仅指定版本，serde = { workspace = true }才是真正导入
[workspace.dependencies]
domain = { path = "domain" }
application = { path = "application" }
infrastructure = { path = "infrastructure" }
interface = { path = "interface" }
migration = { path = "migration" }
common = { path = "common" }

[dependencies]
# 因为在父项目使用了interface的模块用于启动程序，所以要将依赖导入
interface = { workspace = true }

在我的项目中有多个lib crate

• cargo new的main.rs是binary crate
• cargo new --lib的是lib crate

执行cargo doc --workspace --no-deps将cargo.toml工作区所有lib crate的文档导入

cargo doc --workspace --exclude migration --no-deps这次我们排除了migration这个lib crate