support parsing of docs parameter in account, argument, field directives (#69)

Author: rustopian

codama-attributes/src/codama_directives/account_directive.rs

@@ -27,6 +27,7 @@ impl AccountDirective {
         let mut is_signer = SetOnce::<IsAccountSigner>::new("signer").initial_value(false.into());
         let mut is_optional = SetOnce::<bool>::new("optional").initial_value(false);
         let mut default_value = SetOnce::<InstructionInputValueNode>::new("default_value");
+        let mut docs = SetOnce::<Docs>::new("docs");
         match meta.is_path_or_empty_list() {
             true => (),
             false => meta
@@ -40,6 +41,7 @@ impl AccountDirective {
                         InstructionInputValueNode::from_meta(meta.as_value()?)?,
                         meta,
                     ),
+                    "docs" => docs.set(Docs::from_meta(meta)?, meta),
                     _ => Err(meta.error("unrecognized attribute")),
                 })?,
         }
@@ -49,8 +51,7 @@ impl AccountDirective {
                 is_writable: is_writable.take(meta)?,
                 is_signer: is_signer.take(meta)?,
                 is_optional: is_optional.take(meta)?,
-                // TODO: `docs` for account directives not attached to fields.
-                docs: Docs::default(),
+                docs: docs.option().unwrap_or_default(),
                 default_value: default_value.option(),
             },
         })
@@ -161,4 +162,51 @@ mod tests {
         let error = AccountDirective::parse(&meta, &ctx).unwrap_err();
         assert_eq!(error.to_string(), "name is missing");
     }
+
+    #[test]
+    fn with_docs() {
+        let meta: Meta = syn::parse_quote! { account(name = "stake", writable, docs = "what this account is for") };
+        let item = syn::parse_quote! { struct Foo; };
+        let ctx = AttributeContext::Item(&item);
+        let directive = AccountDirective::parse(&meta, &ctx).unwrap();
+        assert_eq!(
+            directive,
+            AccountDirective {
+                account: InstructionAccountNode {
+                    name: "stake".into(),
+                    is_writable: true,
+                    is_signer: IsAccountSigner::False,
+                    is_optional: false,
+                    default_value: None,
+                    docs: vec!["what this account is for".to_string()].into(),
+                },
+            }
+        );
+    }
+
+    #[test]
+    fn with_docs_array() {
+        let meta: Meta = syn::parse_quote! { account(name = "authority", signer, docs = ["Line 1", "Line 2", "Line 3"]) };
+        let item = syn::parse_quote! { struct Foo; };
+        let ctx = AttributeContext::Item(&item);
+        let directive = AccountDirective::parse(&meta, &ctx).unwrap();
+        assert_eq!(
+            directive,
+            AccountDirective {
+                account: InstructionAccountNode {
+                    name: "authority".into(),
+                    is_writable: false,
+                    is_signer: IsAccountSigner::True,
+                    is_optional: false,
+                    default_value: None,
+                    docs: vec![
+                        "Line 1".to_string(),
+                        "Line 2".to_string(),
+                        "Line 3".to_string()
+                    ]
+                    .into(),
+                },
+            }
+        );
+    }
 }

codama-attributes/src/codama_directives/argument_directive.rs

@@ -4,7 +4,7 @@ use crate::{
     Attribute, CodamaAttribute, CodamaDirective,
 };
 use codama_errors::CodamaError;
-use codama_nodes::{Docs, InstructionArgumentNode};
+use codama_nodes::InstructionArgumentNode;
 use codama_syn_helpers::Meta;
 
 #[derive(Debug, PartialEq)]
@@ -30,7 +30,7 @@ impl ArgumentDirective {
             argument: InstructionArgumentNode {
                 name: consumer.name.take(meta)?,
                 r#type: consumer.r#type.take(meta)?,
-                docs: Docs::default(),
+                docs: consumer.docs.option().unwrap_or_default(),
                 default_value,
                 default_value_strategy,
             },
@@ -106,4 +106,21 @@ mod tests {
             }
         );
     }
+
+    #[test]
+    fn with_docs_string() {
+        let meta: Meta = syn::parse_quote! { argument("cake", number(u8), docs = "The cake") };
+        let directive = ArgumentDirective::parse(&meta).unwrap();
+        assert_eq!(directive.argument.docs, vec!["The cake".to_string()].into());
+    }
+
+    #[test]
+    fn with_docs_array() {
+        let meta: Meta = syn::parse_quote! { argument("cake", number(u8), docs = ["The cake", "must be a lie"]) };
+        let directive = ArgumentDirective::parse(&meta).unwrap();
+        assert_eq!(
+            directive.argument.docs,
+            vec!["The cake".to_string(), "must be a lie".to_string()].into()
+        );
+    }
 }

codama-attributes/src/codama_directives/field_directive.rs

@@ -4,7 +4,7 @@ use crate::{
     Attribute, CodamaAttribute, CodamaDirective,
 };
 use codama_errors::CodamaError;
-use codama_nodes::{Docs, StructFieldTypeNode};
+use codama_nodes::StructFieldTypeNode;
 use codama_syn_helpers::Meta;
 
 #[derive(Debug, PartialEq)]
@@ -30,7 +30,7 @@ impl FieldDirective {
             field: StructFieldTypeNode {
                 name: consumer.name.take(meta)?,
                 r#type: consumer.r#type.take(meta)?,
-                docs: Docs::default(),
+                docs: consumer.docs.option().unwrap_or_default(),
                 default_value,
                 default_value_strategy,
             },
@@ -106,4 +106,21 @@ mod tests {
             }
         );
     }
+
+    #[test]
+    fn with_docs_string() {
+        let meta: Meta = syn::parse_quote! { field("splines", number(u8), docs = "Splines") };
+        let directive = FieldDirective::parse(&meta).unwrap();
+        assert_eq!(directive.field.docs, vec!["Splines".to_string()].into());
+    }
+
+    #[test]
+    fn with_docs_array() {
+        let meta: Meta = syn::parse_quote! { field("age", number(u8), docs = ["Splines", "Must be pre-reticulated"]) };
+        let directive = FieldDirective::parse(&meta).unwrap();
+        assert_eq!(
+            directive.field.docs,
+            vec!["Splines".to_string(), "Must be pre-reticulated".to_string()].into()
+        );
+    }
 }

codama-attributes/src/codama_directives/type_nodes/struct_field_meta_consumer.rs

@@ -3,7 +3,7 @@ use crate::{
     DefaultValueDirective,
 };
 use codama_nodes::{
-    CamelCaseString, DefaultValueStrategy, InstructionInputValueNode, TypeNode, ValueNode,
+    CamelCaseString, DefaultValueStrategy, Docs, InstructionInputValueNode, TypeNode, ValueNode,
 };
 use codama_syn_helpers::{extensions::*, Meta};
 
@@ -13,6 +13,7 @@ pub(crate) struct StructFieldMetaConsumer {
     pub r#type: SetOnce<TypeNode>,
     pub default_value: SetOnce<DefaultValueDirective>,
     pub after: SetOnce<bool>,
+    pub docs: SetOnce<Docs>,
 }
 
 impl MetaConsumer for StructFieldMetaConsumer {
@@ -23,6 +24,7 @@ impl MetaConsumer for StructFieldMetaConsumer {
             r#type: SetOnce::new("type"),
             default_value: SetOnce::new("default_value"),
             after: SetOnce::new("after"),
+            docs: SetOnce::new("docs"),
         }
     }
 
@@ -48,6 +50,10 @@ impl StructFieldMetaConsumer {
                     .set(TypeNode::from_meta(meta.as_value()?)?, meta)?;
                 Ok(None)
             }
+            "docs" => {
+                this.docs.set(Docs::from_meta(&meta)?, meta)?;
+                Ok(None)
+            }
             _ => {
                 if let Ok(value) = meta.as_expr().and_then(|e| e.as_string()) {
                     this.name.set(value.into(), meta)?;

codama-attributes/src/utils/from_meta.rs

@@ -1,4 +1,4 @@
-use codama_nodes::{BytesEncoding, IsAccountSigner};
+use codama_nodes::{BytesEncoding, Docs, IsAccountSigner};
 use codama_syn_helpers::{extensions::*, Meta};
 use syn::Expr;
 
@@ -44,3 +44,21 @@ impl FromMeta for BytesEncoding {
         Err(expr.error("expected one of: \"base16\", \"base58\", \"base64\", \"utf8\""))
     }
 }
+
+impl FromMeta for Docs {
+    fn from_meta(meta: &Meta) -> syn::Result<Self> {
+        match meta {
+            Meta::PathList(pl) if pl.eq_token.is_some() => {
+                let strings: Vec<String> = pl
+                    .as_meta_list()
+                    .parse_comma_args::<syn::LitStr>()?
+                    .into_iter()
+                    .map(|lit| lit.value())
+                    .collect();
+                Ok(strings.into())
+            }
+            Meta::PathValue(pv) => pv.value.as_expr()?.as_string().map(|s| vec![s].into()),
+            _ => Err(meta.error("expected a string or array of strings")),
+        }
+    }
+}