From b709729c89120dcd7947d0f09bf7991f1faa4c27 Mon Sep 17 00:00:00 2001
From: "M@ Dunlap" <mrd@vicarious.com>
Date: Fri, 18 Oct 2019 10:17:54 -0700
Subject: [PATCH] add docstrings for generated getters and setters

improve getter/setter method docs
---
 prost-derive/src/field/map.rs    |  8 +++++++
 prost-derive/src/field/scalar.rs | 39 ++++++++++++++++++++++++++++----
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/prost-derive/src/field/map.rs b/prost-derive/src/field/map.rs
index 4d49d8dc7..57a838bf1 100644
--- a/prost-derive/src/field/map.rs
+++ b/prost-derive/src/field/map.rs
@@ -256,10 +256,18 @@ impl Field {
                 quote!()
             };
 
+            let get_doc = format!(
+                "Returns the enum value for the corresponding key in `{}`, \
+                 or `None` if the entry does not exist or it is not a valid enum value.",
+                ident,
+            );
+            let insert_doc = format!("Inserts a key value pair into `{}`.", ident);
             Some(quote! {
+                #[doc=#get_doc]
                 pub fn #get(&self, key: #key_ref_ty) -> ::std::option::Option<#ty> {
                     self.#ident.get(#take_ref key).cloned().and_then(#ty::from_i32)
                 }
+                #[doc=#insert_doc]
                 pub fn #insert(&mut self, key: #key_ty, value: #ty) -> ::std::option::Option<#ty> {
                     self.#ident.insert(key, value as i32).and_then(#ty::from_i32)
                 }
diff --git a/prost-derive/src/field/scalar.rs b/prost-derive/src/field/scalar.rs
index b728b64af..acae62131 100644
--- a/prost-derive/src/field/scalar.rs
+++ b/prost-derive/src/field/scalar.rs
@@ -278,38 +278,63 @@ impl Field {
         if ident_str.starts_with("r#") {
             ident_str = ident_str[2..].to_owned();
         }
-        let set = Ident::new(&format!("set_{}", ident_str), Span::call_site());
-        let push = Ident::new(&format!("push_{}", ident_str), Span::call_site());
+
         if let Ty::Enumeration(ref ty) = self.ty {
+            let set = Ident::new(&format!("set_{}", ident_str), Span::call_site());
+            let set_doc = format!("Sets `{}` to the provided enum value.", ident_str);
             Some(match self.kind {
                 Kind::Plain(ref default) | Kind::Required(ref default) => {
+                    let get_doc = format!(
+                        "Returns the enum value of `{}`, \
+                         or the default if the field is set to an invalid enum value.",
+                        ident_str,
+                    );
                     quote! {
+                        #[doc=#get_doc]
                         pub fn #ident(&self) -> #ty {
                             #ty::from_i32(self.#ident).unwrap_or(#default)
                         }
 
+                        #[doc=#set_doc]
                         pub fn #set(&mut self, value: #ty) {
                             self.#ident = value as i32;
                         }
                     }
                 }
                 Kind::Optional(ref default) => {
+                    let get_doc = format!(
+                        "Returns the enum value of `{}`, \
+                         or the default if the field is unset or set to an invalid enum value.",
+                        ident_str,
+                    );
                     quote! {
+                        #[doc=#get_doc]
                         pub fn #ident(&self) -> #ty {
                             self.#ident.and_then(#ty::from_i32).unwrap_or(#default)
                         }
 
+                        #[doc=#set_doc]
                         pub fn #set(&mut self, value: #ty) {
                             self.#ident = ::std::option::Option::Some(value as i32);
                         }
                     }
                 }
                 Kind::Repeated | Kind::Packed => {
+                    let iter_doc = format!(
+                        "Returns an iterator which yields the valid enum values contained in `{}`.",
+                        ident_str,
+                    );
+                    let push = Ident::new(&format!("push_{}", ident_str), Span::call_site());
+                    let push_doc = format!("Appends the provided enum value to `{}`.", ident_str);
                     quote! {
-                        pub fn #ident(&self) -> ::std::iter::FilterMap<::std::iter::Cloned<::std::slice::Iter<i32>>,
-                                                                       fn(i32) -> Option<#ty>> {
+                        #[doc=#iter_doc]
+                        pub fn #ident(&self) -> ::std::iter::FilterMap<
+                            ::std::iter::Cloned<::std::slice::Iter<i32>>,
+                            fn(i32) -> Option<#ty>,
+                        > {
                             self.#ident.iter().cloned().filter_map(#ty::from_i32)
                         }
+                        #[doc=#push_doc]
                         pub fn #push(&mut self, value: #ty) {
                             self.#ident.push(value as i32);
                         }
@@ -325,7 +350,13 @@ impl Field {
                 quote!(::std::option::Option::Some(ref val) => &val[..],)
             };
 
+            let get_doc = format!(
+                "Returns the value of `{0}`, or the default value if `{0}` is unset.",
+                ident_str,
+            );
+
             Some(quote! {
+                #[doc=#get_doc]
                 pub fn #ident(&self) -> #ty {
                     match self.#ident {
                         #match_some