如何弄清楚Rust宏的参数和语法？

Question

例如：使用

salvo_oapi

板条箱，我有以下代码：

use bson::doc;
use salvo::prelude::*;

use crate::{
    features::auth::models::user::{get_user_from_depot, User},
    utils::api_error::ApiError,
};

/// How to know what macros this cargo supports? Docs are unclear
#[endpoint(tags("Auth"), operationId = "fetch_user")]
pub async fn fetch_user(depot: &mut Depot) -> Result<Json<User>, ApiError> {
    let user = get_user_from_depot(depot)?;

    Ok(Json(user.clone()))
}

当我打开货物或宏源代码时，我找不到任何允许的宏所在的位置以及它们的名称和输入是什么；非常令人沮丧的经历。

Answer 1

有关

endpoint

宏的具体问题/评论确实由

salvo-oapi

的开发人员更好地解决了。最好提出一个问题：文档here应该描述了如何使用宏，或者至少链接到指南/教程。

更一般地说，宏（任何类型）的文档并不像 Rust 中的函数文档那么容易。这是因为宏在设计上可以以非标准方式处理 AST，以允许语法扩展（在合理范围内）。因此，一个属性宏可能使用语法

#[foo(a = 1, b = 2)]

，另一个可能使用

#[foo(1, 2)]

，而另一个属性宏可能只是

#[foo]

，并带有来自带注释的项目主体的附加“输入”。

Answer 2

我同意有时找到记录的内容可能会令人沮丧，尤其是当它不在您期望的位置时。但开发人员也很难预测用户进入文档的入口点在哪里。

直接转到

salvo_oapi::endpoint

的定义没有记录，而且来源也很少，因为属性宏本身实际上并不执行任何操作。

相反，它稍后在

salvo_oapi::endpoint

模块中进行处理，因此开发人员可能认为在那里记录它是很自然的。

在这些情况下，我建议从板条箱文档的顶部开始，看看它们是否有任何提及。在

salvo_oapi

板条箱文档中，您可以找到顶部带有端点的模块列表，并有很好的描述：

Endpoint 属性宏实现修饰函数的 OpenAPI 路径。

在属性宏部分，您可以发现

endpoint

是唯一可用的属性宏。