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

Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com>

proxmox-api-macro/src/api.rs

@@ -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"))?;
 
+    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(&doc_comment, doc_span));
+                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)?;

proxmox-api-macro/tests/api1.rs

@@ -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,