glib-macros: Properties: allow setting getter and setter docs

In the previous commit we made it so we copy the docs for a `#[property]` in to
the getter. This was an improvement but it still did not allow for any doc comments
on the setter that might be relevant only there.

Here we introduce the ability to specify doc comments for the getter and setter
individually via the use of the header syntax to switch between them. By writing
`# Getter` or `# Setter` in a line, you make the lines following it go to the
getter or setter function definitions.

If neither of these values exist, we copy the doc comments to both. If you use
these values, then anything in the doc comments before the first one is
discarded.

Author: carlosmn

examples/object_subclass/author.rs

@@ -21,6 +21,13 @@ mod imp {
         /// A helpful name-surname combination.
         #[property(name = "name-surname", get = |author: &Self| format!("{} {}", author.name.borrow(), author.surname.borrow()))]
         name: RefCell<String>,
+        /// # Getter
+        ///
+        /// This is how you can get the surname of the author.
+        ///
+        /// # Setter
+        ///
+        /// You can change the surname of the author too if you want.
         #[property(get, set)]
         surname: RefCell<String>,
     }

glib-macros/src/properties.rs

@@ -569,6 +569,50 @@ fn strip_raw_prefix_from_name(name: &LitStr) -> LitStr {
     )
 }
 
+/// Splits the comments for a property between the getter and setter
+///
+/// The return tuple is the attributes to copy over into the getter and setter
+/// respectively.
+fn arrange_property_comments(comments: &[Attribute]) -> (Vec<&Attribute>, Vec<&Attribute>) {
+    let mut untagged = vec![];
+    let mut getter = vec![];
+    let mut setter = vec![];
+    let mut saw_section = false;
+
+    // We start with no tags so if the programmer doesn't split the comments we can still arrange them.
+    let mut current_section = &mut untagged;
+    for attr in comments {
+        if let syn::Meta::NameValue(meta) = &attr.meta {
+            if let syn::Expr::Lit(expr) = &meta.value {
+                if let syn::Lit::Str(lit_str) = &expr.lit {
+                    // Now that we have the one line of comment, see if we need
+                    // to switch a particular section to be the active one (via
+                    // the header syntax) or add the current line to the active
+                    // section.
+                    match lit_str.value().trim() {
+                        "# Getter" => {
+                            current_section = &mut getter;
+                            saw_section = true;
+                        }
+                        "# Setter" => {
+                            current_section = &mut setter;
+                            saw_section = true;
+                        }
+                        _ => current_section.push(attr),
+                    }
+                }
+            }
+        }
+    }
+
+    // If no sections were defined then we put the same in both
+    if !saw_section {
+        return (untagged.clone(), untagged);
+    }
+
+    (getter, setter)
+}
+
 fn expand_impl_getset_properties(props: &[PropDesc]) -> Vec<syn::ImplItemFn> {
     let crate_ident = crate_ident_new();
     let defs = props.iter().filter(|p| !p.is_overriding()).map(|p| {
@@ -577,6 +621,8 @@ fn expand_impl_getset_properties(props: &[PropDesc]) -> Vec<syn::ImplItemFn> {
         let ident = name_to_ident(name);
         let ty = &p.ty;
 
+        let (getter_docs, setter_docs) = arrange_property_comments(&p.comments);
+
         let mut getter: Option<syn::ImplItemFn> = p.get.is_some().then(|| {
             let span = p.attrs_span;
             parse_quote_spanned!(span=>
@@ -589,12 +635,12 @@ fn expand_impl_getset_properties(props: &[PropDesc]) -> Vec<syn::ImplItemFn> {
         });
 
         if let Some(ref mut getter) = getter {
-            for lit in &p.comments {
-                getter.attrs.push(lit.clone());
+            for attr in getter_docs {
+                getter.attrs.push(attr.clone());
             }
         }
 
-        let setter = (p.set.is_some() && !p.is_construct_only).then(|| {
+        let mut setter: Option<syn::ImplItemFn> = (p.set.is_some() && !p.is_construct_only).then(|| {
             let ident = format_ident!("set_{}", ident);
             let target_ty = quote!(<<#ty as #crate_ident::property::Property>::Value as #crate_ident::prelude::HasParamSpec>::SetValue);
             let set_ty = if p.nullable {
@@ -619,6 +665,13 @@ fn expand_impl_getset_properties(props: &[PropDesc]) -> Vec<syn::ImplItemFn> {
                 }
             )
         });
+
+        if let Some(ref mut setter) = setter {
+            for attr in setter_docs {
+                setter.attrs.push(attr.clone());
+            }
+        }
+
         [getter, setter]
     });
     defs.flatten() // flattens []