From 366b50dee76be0b74e9f5349e152c9cef74ec1b8 Mon Sep 17 00:00:00 2001
From: Wolfgang Bumiller <w.bumiller@proxmox.com>
Date: Tue, 26 Nov 2019 13:39:20 +0100
Subject: [PATCH] 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    | 31 ++++++++++++++++++++++++++-----
 proxmox-api-macro/tests/api1.rs |  3 +--
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/proxmox-api-macro/src/api.rs b/proxmox-api-macro/src/api.rs
index a41a16e4..5e9ab0e4 100644
--- a/proxmox-api-macro/src/api.rs
+++ b/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"))?;
 
-    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)?;
diff --git a/proxmox-api-macro/tests/api1.rs b/proxmox-api-macro/tests/api1.rs
index 2b4a726b..6163b94a 100644
--- a/proxmox-api-macro/tests/api1.rs
+++ b/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,