Proxmox/proxmox
5
0
Fork 1
Code Issues Pull Requests Releases Activity

api-macro: understand a 'Returns:' section in function doc comments

Browse Source 
Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>
This commit is contained in:
Wolfgang Bumiller 2019-11-26 13:39:20 +01:00
parent b899c3e9ee
commit 366b50dee7
2 changed files with 27 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
proxmox-api-macro/src/api.rs
View File

@ -506,8 +506,32 @@ pub(crate) fn api(_attr: TokenStream, item: TokenStream) -> Result<TokenStream,
let mut input_schema =
input_schema.ok_or_else(|| format_err!(sig_span, "missing input schema"))?;
if input_schema.description.is_none() {
input_schema.description = Some(syn::LitStr::new(&doc_comment, doc_span));
let mut returns_schema =
returns_schema.ok_or_else(|| format_err!(sig_span, "missing returns schema"))?;
// If we have a doc comment, allow automatically inferring the description for the input and
// output objects:
if !doc_comment.is_empty() {
let mut parts = doc_comment.splitn(2, "\nReturns:");
if let Some(first) = parts.next() {
if input_schema.description.is_none() {
input_schema.description = Some(syn::LitStr::new(first.trim(), doc_span));
}
}
if let Some(second) = parts.next() {
if returns_schema.description.is_none() {
returns_schema.description = Some(syn::LitStr::new(second.trim(), doc_span));
}
}
if parts.next().is_some() {
bail!(
doc_span,
"multiple 'Returns:' sections found in doc comment!"
);
}
}
let input_schema = {
@ -516,9 +540,6 @@ pub(crate) fn api(_attr: TokenStream, item: TokenStream) -> Result<TokenStream,
ts
};
let returns_schema =
returns_schema.ok_or_else(|| format_err!(sig_span, "missing returns schema"))?;
let returns_schema = {
let mut ts = TokenStream::new();
returns_schema.to_schema(&mut ts)?;

3
proxmox-api-macro/tests/api1.rs
View File

@ -21,7 +21,6 @@ use serde_json::Value;
}
})]
#[returns({
description: "Returns a ticket",
properties: {
"username": {
type: String,
@ -39,7 +38,7 @@ use serde_json::Value;
})]
/// Create or verify authentication ticket.
///
/// Returns: ...
/// Returns: A ticket.
fn create_ticket(
_param: Value,
_info: &ApiMethod,