Issue #3 and #4: Add field documentation and annotation

src/lib.rs

@@ -128,12 +128,18 @@ enum Fields {
 
 /// Defines a struct field.
 #[derive(Debug, Clone)]
-struct Field {
+pub struct Field {
     /// Field name
     name: String,
 
     /// Field type
     ty: Type,
+
+    /// Field documentation
+    documentation: String,
+
+    /// Field annotation
+    annotation: String,
 }
 
 /// Defines an associated type.
@@ -582,6 +588,16 @@ impl Struct {
         self
     }
 
+    /// Push a named field to the struct.
+    ///
+    /// A struct can either set named fields with this function or tuple fields
+    /// with `push_tuple_field`, but not both.
+    pub fn push_field(&mut self, field: Field) -> &mut Self
+    {
+        self.fields.push_named(field);
+        self
+    }
+
     /// Add a named field to the struct.
     ///
     /// A struct can either set named fields with this function or tuple fields
@@ -1073,31 +1089,63 @@ impl AssociatedType {
     }
 }
 
+// ===== impl Field =====
+
+impl Field {
+    /// Return a field definition with the provided name and type
+    pub fn new<T>(name: &str, ty: T) -> Self
+    where T: Into<Type>,
+    {
+        Field {
+            name: name.into(),
+            ty: ty.into(),
+            documentation: String::new(),
+            annotation: String::new(),
+        }
+    }
+
+    /// Set field's documentation.
+    pub fn doc(&mut self, documentation: &str) -> &mut Self {
+        self.documentation = documentation.into();
+        self
+    }
+
+    /// Set field's annotation.
+    pub fn annotation(&mut self, annotation: &str) -> &mut Self {
+        self.annotation = annotation.into();
+        self
+    }
+}
+
 // ===== impl Fields =====
 
 impl Fields {
-    fn named<T>(&mut self, name: &str, ty: T) -> &mut Self
-    where T: Into<Type>,
+    fn push_named(&mut self, field: Field) -> &mut Self
     {
         match *self {
             Fields::Empty => {
-                *self = Fields::Named(vec![Field {
-                    name: name.to_string(),
-                    ty: ty.into(),
-                }]);
+                *self = Fields::Named(vec![field]);
             }
             Fields::Named(ref mut fields) => {
-                fields.push(Field {
-                    name: name.to_string(),
-                    ty: ty.into(),
-                });
+                fields.push(field);
             }
             _ => panic!("field list is named"),
         }
 
         self
     }
 
+    fn named<T>(&mut self, name: &str, ty: T) -> &mut Self
+    where T: Into<Type>,
+    {
+        self.push_named(Field {
+            name: name.to_string(),
+            ty: ty.into(),
+            documentation: String::new(),
+            annotation: String::new(),
+        })
+    }
+
     fn tuple<T>(&mut self, ty: T) -> &mut Self
     where T: Into<Type>,
     {
@@ -1121,6 +1169,12 @@ impl Fields {
 
                 fmt.block(|fmt| {
                     for f in fields {
+                        if !f.documentation.is_empty() {
+                            write!(fmt, "/// {}\n", f.documentation)?;
+                        }
+                        if !f.annotation.is_empty() {
+                            write!(fmt, "{}\n", f.annotation)?;
+                        }
                         write!(fmt, "{}: ", f.name)?;
                         f.ty.fmt(fmt)?;
                         write!(fmt, ",\n")?;
@@ -1196,6 +1250,8 @@ impl Impl {
         self.assoc_tys.push(Field {
             name: name.to_string(),
             ty: ty.into(),
+            documentation: String::new(),
+            annotation: String::new(),
         });
 
         self
@@ -1340,6 +1396,11 @@ impl Function {
         self.args.push(Field {
             name: name.to_string(),
             ty: ty.into(),
+            // While a `Field` is used here, both `documentation`
+            // and `annotation` does not make sense for function arguments.
+            // Simply use empty strings.
+            documentation: String::new(),
+            annotation: String::new(),
         });
 
         self

tests/codegen.rs

@@ -1,6 +1,6 @@
 extern crate codegen;
 
-use codegen::Scope;
+use codegen::{Field, Scope, Struct};
 
 #[test]
 fn empty_scope() {
@@ -26,6 +26,59 @@ struct Foo {
     assert_eq!(scope.to_string(), &expect[1..]);
 }
 
+#[test]
+fn struct_with_pushed_field() {
+    let mut scope = Scope::new();
+    let mut struct_ = Struct::new("Foo");
+    let mut field = Field::new("one", "usize");
+    struct_.push_field(field);
+    scope.push_struct(struct_);
+
+    let expect = r#"
+struct Foo {
+    one: usize,
+}"#;
+
+    assert_eq!(scope.to_string(), &expect[1..]);
+}
+
+#[test]
+fn single_struct_documented_field() {
+    let mut scope = Scope::new();
+
+    let doc = "Field's documentation";
+    let anot = r#"#[serde(rename = "bar")]"#;
+
+    let mut struct_ = Struct::new("Foo");
+
+    let mut field1 = Field::new("one", "usize");
+    field1.doc(doc);
+    struct_.push_field(field1);
+
+    let mut field2 = Field::new("two", "usize");
+    field2.annotation(anot);
+    struct_.push_field(field2);
+
+    let mut field3 = Field::new("three", "usize");
+    field3.doc(doc).annotation(anot);
+    struct_.push_field(field3);
+
+    scope.push_struct(struct_);
+
+    let expect = r#"
+struct Foo {
+    /// Field's documentation
+    one: usize,
+    #[serde(rename = "bar")]
+    two: usize,
+    /// Field's documentation
+    #[serde(rename = "bar")]
+    three: usize,
+}"#;
+
+    assert_eq!(scope.to_string(), &expect[1..]);
+}
+
 #[test]
 fn empty_struct() {
     let mut scope = Scope::new();