使用过程宏生成rust的API文档。因为cargo doc 文档内容太多。如果用作API使用文档不太适合。所以使用过程宏来实现生成简洁的API文档
使用过程宏来标记API,并基于API的注释来生成API文档。生成的文档文件名称为:doc.data.
文档生成发生在使用命令 cargo check 或者cargo build 时。如果文档格式不正确,会阻止check或者build
- doc_def : API文档格式的基本定义
- doc_macro : api文档的宏定义
- doc_server : api文档的浏览服务. 可以通过使用参数 -p 指定运行端口
- rust_document_generator : 是包含了doc_def 与doc_macro 的结合体,仅仅是为了方便使用
/// this is the header of one api document
/// + multiple line can start with "+" to preserve extra white space
#[rust_document_generator::doc_header]
fn main(){
}
/// module the name of this module
/// fn HelloWorld /v1/HelloWorld post # this is figure out the api base info, such as "fn {ApiName} {RequestPath} {HttpMethod} {Description}"
/// + api description can have multiple line. and it can start with "+" to preserve extra white space
/// param
/// Name string required #this is the param info. such as "{ParamName} {ParamType} {required/optional} {description}". the description is only one line
/// return # this is the return segment. such as "reutrn {return description} \r\n {return content}"
/// +{
/// + "Desc":"String 其他描述"
/// +}
/// +
#[rust_document_generator::api]
fn hello_word(name:String,extra_hellor:String)->String{
format!("hello world {}",&name)
}
说明
- 使用rust_document_generator::doc_header 指定函数的注释做为API的头信息。支持html标签,支持多行。如果需要保持多行的格式,则使用+ 开头
- 使用rust_document_generator::api 指定API。被指定的API会要求函数注释满足API注释的格式。否则执行cargo check时会报错
API注释格式要求
- 使用module 指定API所属模块,格式: module {模块名}
- 使用fn 指定 API的基本信息,格式: fn {API名} {API请求路径} {API描述} API描述可以有多行
- 使用param 指定请求参数。每个参数单独占一行。 参数具体格式是: {参数名} {参数类型} {required|optional} {参数描述}
- 使用return 指定返回值。 具体格式: return {可选的返回描述} \r\n {返回的具体内容描述}
现在返回值说明只支持字符串。后期会考虑添加对指定struct的支持