ToSchema and IntoParams derive macros now support multiline comments (#…

…359)

Make `description` field accept whole doc comment instead of the first line only.

Resolves #358

utoipa-gen/src/component/into_params.rs

@@ -277,8 +277,8 @@ impl ToTokens for Param<'_> {
                     .rename_all
                     .map(|rename_all| rename_all.as_rename_rule())
             });
-        let name =
-            super::rename::<FieldRename>(name, rename_to, rename_all).unwrap_or(Cow::Borrowed(name));
+        let name = super::rename::<FieldRename>(name, rename_to, rename_all)
+            .unwrap_or(Cow::Borrowed(name));
         let type_tree = TypeTree::from_type(&field.ty);
 
         tokens.extend(quote! { utoipa::openapi::path::ParameterBuilder::new()
@@ -297,7 +297,9 @@ impl ToTokens for Param<'_> {
         if let Some(deprecated) = super::get_deprecated(&field.attrs) {
             tokens.extend(quote! { .deprecated(Some(#deprecated)) });
         }
-        if let Some(comment) = CommentAttributes::from_attributes(&field.attrs).first() {
+        let attributes = CommentAttributes::from_attributes(&field.attrs);
+        if !attributes.is_empty() {
+            let comment = attributes.join("\n");
             tokens.extend(quote! {
                 .description(Some(#comment))
             })

utoipa-gen/src/component/schema.rs

@@ -308,7 +308,9 @@ impl ToTokens for NamedStructSchema<'_> {
             tokens.extend(struct_features.to_token_stream())
         }
 
-        if let Some(comment) = CommentAttributes::from_attributes(self.attributes).first() {
+        let attributes = CommentAttributes::from_attributes(self.attributes);
+        if !attributes.is_empty() {
+            let comment = attributes.join("\n");
             tokens.extend(quote! {
                 .description(Some(#comment))
             })
@@ -432,7 +434,9 @@ impl ToTokens for UnnamedStructSchema<'_> {
             }
         };
 
-        if let Some(comment) = CommentAttributes::from_attributes(self.attributes).first() {
+        let attributes = CommentAttributes::from_attributes(self.attributes);
+        if !attributes.is_empty() {
+            let comment = attributes.join("\n");
             if !is_object {
                 tokens.extend(quote! {
                     .description(Some(#comment))
@@ -542,7 +546,9 @@ impl ToTokens for EnumSchemaType<'_> {
             tokens.extend(quote! { .deprecated(Some(#deprecated)) });
         }
 
-        if let Some(comment) = CommentAttributes::from_attributes(attributes).first() {
+        let attributes = CommentAttributes::from_attributes(attributes);
+        if !attributes.is_empty() {
+            let comment = attributes.join("\n");
             tokens.extend(quote! {
                 .description(Some(#comment))
             })
@@ -1064,8 +1070,13 @@ impl ToTokens for SchemaProperty<'_> {
                     utoipa::openapi::ObjectBuilder::new().additional_properties(Some(#schema_property))
                 });
 
-                if let Some(description) = self.comments.and_then(|attributes| attributes.0.first())
-                {
+                if let Some(description) = self.comments.and_then(|attributes| {
+                    if attributes.is_empty() {
+                        None
+                    } else {
+                        Some(attributes.join("\n"))
+                    }
+                }) {
                     tokens.extend(quote! {
                         .description(Some(#description))
                     })
@@ -1143,9 +1154,13 @@ impl ToTokens for SchemaProperty<'_> {
                             })
                         }
 
-                        if let Some(description) =
-                            self.comments.and_then(|attributes| attributes.0.first())
-                        {
+                        if let Some(description) = self.comments.and_then(|attributes| {
+                            if attributes.is_empty() {
+                                None
+                            } else {
+                                Some(attributes.join("\n"))
+                            }
+                        }) {
                             tokens.extend(quote! {
                                 .description(Some(#description))
                             })

utoipa-gen/tests/schema_derive_test.rs

@@ -217,8 +217,8 @@ fn derive_struct_with_comments_success() {
     let account = api_doc! {
         /// This is user account dto object
         ///
-        /// Detailed documentation here
-        /// Only first line is added to the description so far
+        /// Detailed documentation here.
+        /// More than the first line is added to the description as well.
         struct Account {
             /// Database autogenerated id
             id: i64,
@@ -229,7 +229,7 @@ fn derive_struct_with_comments_success() {
     };
 
     assert_value! {account=>
-        "description" = r#""This is user account dto object""#, "Account description"
+        "description" = r#""This is user account dto object\n\nDetailed documentation here.\nMore than the first line is added to the description as well.""#, "Account description"
         "properties.id.description" = r#""Database autogenerated id""#, "Account id description"
         "properties.username.description" = r#""Users username""#, "Account username description"
         "properties.role_ids.type" = r#""array""#, "Account role_ids type"
@@ -244,8 +244,8 @@ fn derive_enum_with_comments_success() {
     let account = api_doc! {
         /// This is user account status enum
         ///
-        /// Detailed documentation here
-        /// Only first line is added to the description so far
+        /// Detailed documentation here.
+        /// More than the first line is added to the description as well.
         enum AccountStatus {
             /// When user is valid to login, these enum variant level docs are omitted!!!!!
             /// Since the OpenAPI spec does not have a place to put such infomation.
@@ -257,7 +257,7 @@ fn derive_enum_with_comments_success() {
     };
 
     assert_value! {account=>
-        "description" = r#""This is user account status enum""#, "AccountStatus description"
+        "description" = r#""This is user account status enum\n\nDetailed documentation here.\nMore than the first line is added to the description as well.""#, "AccountStatus description"
     }
 }
 
@@ -286,7 +286,7 @@ fn derive_struct_unnamed_fields_tuple_with_same_type_success() {
         "type" = r#""array""#, "Point type"
         "items.type" = r#""number""#, "Point items type"
         "items.format" = r#""float""#, "Point items format"
-        "items.description" = r#""Contains x and y coordinates""#, "Point items description"
+        "items.description" = r#""Contains x and y coordinates\n\nCoordinates are used to pinpoint location on a map""#, "Point items description"
         "maxItems" = r#"2"#, "Wrapper max items"
         "minItems" = r#"2"#, "Wrapper min items"
     }