From da65fe5a52a2103ad481d003cf4d6db30ce3dd1c Mon Sep 17 00:00:00 2001 From: Richard Dodd Date: Sat, 29 Sep 2018 15:06:23 +0100 Subject: [PATCH 1/3] Some docs --- serde_derive/src/internals/ast.rs | 18 ++++++++++++++++++ serde_derive/src/internals/attr.rs | 2 +- serde_derive/src/internals/case.rs | 6 ++++++ serde_derive/src/internals/ctxt.rs | 10 ++++++++++ 4 files changed, 35 insertions(+), 1 deletion(-) diff --git a/serde_derive/src/internals/ast.rs b/serde_derive/src/internals/ast.rs index f780db2f..305d5f06 100644 --- a/serde_derive/src/internals/ast.rs +++ b/serde_derive/src/internals/ast.rs @@ -6,24 +6,36 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +//! A serde ast, parsed from the syn ast and ready for codegen. + use internals::attr; use internals::check; use internals::{Ctxt, Derive}; use syn; use syn::punctuated::Punctuated; +/// A source data structure annotated with `#[derive(Derialize)]` and/or `#[derive(Deserialize)]`, +/// parsed into an internal representation. pub struct Container<'a> { + /// The struct or enum name (without generics). pub ident: syn::Ident, + /// Attributes on the structure, parsed for serde. pub attrs: attr::Container, + /// The contents of the struct or enum. pub data: Data<'a>, + /// Any generics on the struct or enum. pub generics: &'a syn::Generics, } +/// The fields of a struct or enum. +/// +/// Analagous to `syn::Data`. pub enum Data<'a> { Enum(Vec>), Struct(Style, Vec>), } +/// A variant of an enum. pub struct Variant<'a> { pub ident: syn::Ident, pub attrs: attr::Variant, @@ -31,6 +43,7 @@ pub struct Variant<'a> { pub fields: Vec>, } +/// A variant of a struct. pub struct Field<'a> { pub member: syn::Member, pub attrs: attr::Field, @@ -40,13 +53,18 @@ pub struct Field<'a> { #[derive(Copy, Clone)] pub enum Style { + /// Named fields. Struct, + /// Many unnamed fields. Tuple, + /// One unnamed field. Newtype, + /// No fields. Unit, } impl<'a> Container<'a> { + /// Convert the raw syn ast into a parsed container object, collecting errors in `cx`. pub fn from_ast(cx: &Ctxt, item: &'a syn::DeriveInput, derive: Derive) -> Container<'a> { let mut attrs = attr::Container::from_ast(cx, item); diff --git a/serde_derive/src/internals/attr.rs b/serde_derive/src/internals/attr.rs index 711339b1..ca159b2c 100644 --- a/serde_derive/src/internals/attr.rs +++ b/serde_derive/src/internals/attr.rs @@ -106,7 +106,7 @@ impl Name { } } -/// Represents container (e.g. struct) attribute information +/// Represents struct or enum attribute information. pub struct Container { name: Name, transparent: bool, diff --git a/serde_derive/src/internals/case.rs b/serde_derive/src/internals/case.rs index a84b7d0c..e5162ca9 100644 --- a/serde_derive/src/internals/case.rs +++ b/serde_derive/src/internals/case.rs @@ -6,6 +6,9 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. +//! Stuff to handle where the case of the source (e.g. `my-field`) is different to the +//! field/variant (e.g. `my_field`). + // See https://users.rust-lang.org/t/psa-dealing-with-warning-unused-import-std-ascii-asciiext-in-today-s-nightly/13726 #[allow(deprecated, unused_imports)] use std::ascii::AsciiExt; @@ -14,6 +17,7 @@ use std::str::FromStr; use self::RenameRule::*; +/// The different possible ways to change case of fields in a struct, or variants in an enum. #[derive(PartialEq)] pub enum RenameRule { /// Don't apply a default rename rule. @@ -40,6 +44,7 @@ pub enum RenameRule { } impl RenameRule { + /// Apply a renaming rule to an enum variant, returning the version expected in the source. pub fn apply_to_variant(&self, variant: &str) -> String { match *self { None | PascalCase => variant.to_owned(), @@ -64,6 +69,7 @@ impl RenameRule { } } + /// Apply a renaming rule to a struct field, returning the version expected in the source. pub fn apply_to_field(&self, field: &str) -> String { match *self { None | LowerCase | SnakeCase => field.to_owned(), diff --git a/serde_derive/src/internals/ctxt.rs b/serde_derive/src/internals/ctxt.rs index 60bf876c..5aa6bbdb 100644 --- a/serde_derive/src/internals/ctxt.rs +++ b/serde_derive/src/internals/ctxt.rs @@ -10,18 +10,27 @@ use std::cell::RefCell; use std::fmt::Display; use std::thread; +/// A type to collect errors together and format them. +/// +/// Dropping this object will cause a panic. It must be consumed using `check`. +/// +/// References can be shared since this type uses run-time exclusive mut checking. #[derive(Default)] pub struct Ctxt { + // The contents will be set to `None` during checking. This is so that checking can be + // enforced. errors: RefCell>>, } impl Ctxt { + /// Create a new context object pub fn new() -> Self { Ctxt { errors: RefCell::new(Some(Vec::new())), } } + /// Add an error to the context object pub fn error(&self, msg: T) { self.errors .borrow_mut() @@ -30,6 +39,7 @@ impl Ctxt { .push(msg.to_string()); } + /// Consume this object, producing a formatted error string if there are errors. pub fn check(self) -> Result<(), String> { let mut errors = self.errors.borrow_mut().take().unwrap(); match errors.len() { From f1073dca04923b50895bf4df366e52ffa979d96b Mon Sep 17 00:00:00 2001 From: Richard Dodd Date: Sun, 30 Sep 2018 12:34:52 +0100 Subject: [PATCH 2/3] Make the recommended changed from code review. --- serde_derive/src/internals/ast.rs | 6 +++--- serde_derive/src/internals/case.rs | 4 ++-- serde_derive/src/internals/ctxt.rs | 6 ++++-- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/serde_derive/src/internals/ast.rs b/serde_derive/src/internals/ast.rs index 305d5f06..bb2c4690 100644 --- a/serde_derive/src/internals/ast.rs +++ b/serde_derive/src/internals/ast.rs @@ -6,7 +6,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! A serde ast, parsed from the syn ast and ready for codegen. +//! A serde ast, parsed from the syn ast and ready to generate rust code. use internals::attr; use internals::check; @@ -14,7 +14,7 @@ use internals::{Ctxt, Derive}; use syn; use syn::punctuated::Punctuated; -/// A source data structure annotated with `#[derive(Derialize)]` and/or `#[derive(Deserialize)]`, +/// A source data structure annotated with `#[derive(Serialize)]` and/or `#[derive(Deserialize)]`, /// parsed into an internal representation. pub struct Container<'a> { /// The struct or enum name (without generics). @@ -43,7 +43,7 @@ pub struct Variant<'a> { pub fields: Vec>, } -/// A variant of a struct. +/// A field of a struct. pub struct Field<'a> { pub member: syn::Member, pub attrs: attr::Field, diff --git a/serde_derive/src/internals/case.rs b/serde_derive/src/internals/case.rs index e5162ca9..87428144 100644 --- a/serde_derive/src/internals/case.rs +++ b/serde_derive/src/internals/case.rs @@ -6,8 +6,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Stuff to handle where the case of the source (e.g. `my-field`) is different to the -//! field/variant (e.g. `my_field`). +//! Utility code to assist converting the case of the source (e.g. `my-field`, `MY_FIELD`) to the +//! rust-styled field/variant (e.g. `my_field`, `MyType`). // See https://users.rust-lang.org/t/psa-dealing-with-warning-unused-import-std-ascii-asciiext-in-today-s-nightly/13726 #[allow(deprecated, unused_imports)] diff --git a/serde_derive/src/internals/ctxt.rs b/serde_derive/src/internals/ctxt.rs index 5aa6bbdb..51c72f7c 100644 --- a/serde_derive/src/internals/ctxt.rs +++ b/serde_derive/src/internals/ctxt.rs @@ -23,14 +23,16 @@ pub struct Ctxt { } impl Ctxt { - /// Create a new context object + /// Create a new context object. + /// + /// This object contains no errors, but will still trigger a panic if it is not `check`ed. pub fn new() -> Self { Ctxt { errors: RefCell::new(Some(Vec::new())), } } - /// Add an error to the context object + /// Add an error to the context object. pub fn error(&self, msg: T) { self.errors .borrow_mut() From 80765eb453308f028754610c3fb9cf465f8ad7e4 Mon Sep 17 00:00:00 2001 From: Richard Dodd Date: Sun, 30 Sep 2018 15:17:47 +0100 Subject: [PATCH 3/3] Make suggested changes --- serde_derive/src/internals/ast.rs | 6 +++--- serde_derive/src/internals/case.rs | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/serde_derive/src/internals/ast.rs b/serde_derive/src/internals/ast.rs index bb2c4690..c81e9cf9 100644 --- a/serde_derive/src/internals/ast.rs +++ b/serde_derive/src/internals/ast.rs @@ -6,7 +6,7 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! A serde ast, parsed from the syn ast and ready to generate rust code. +//! A Serde ast, parsed from the Syn ast and ready to generate Rust code. use internals::attr; use internals::check; @@ -19,7 +19,7 @@ use syn::punctuated::Punctuated; pub struct Container<'a> { /// The struct or enum name (without generics). pub ident: syn::Ident, - /// Attributes on the structure, parsed for serde. + /// Attributes on the structure, parsed for Serde. pub attrs: attr::Container, /// The contents of the struct or enum. pub data: Data<'a>, @@ -64,7 +64,7 @@ pub enum Style { } impl<'a> Container<'a> { - /// Convert the raw syn ast into a parsed container object, collecting errors in `cx`. + /// Convert the raw Syn ast into a parsed container object, collecting errors in `cx`. pub fn from_ast(cx: &Ctxt, item: &'a syn::DeriveInput, derive: Derive) -> Container<'a> { let mut attrs = attr::Container::from_ast(cx, item); diff --git a/serde_derive/src/internals/case.rs b/serde_derive/src/internals/case.rs index 87428144..43f879fc 100644 --- a/serde_derive/src/internals/case.rs +++ b/serde_derive/src/internals/case.rs @@ -6,8 +6,8 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Utility code to assist converting the case of the source (e.g. `my-field`, `MY_FIELD`) to the -//! rust-styled field/variant (e.g. `my_field`, `MyType`). +//! Code to convert the Rust-styled field/variant (e.g. `my_field`, `MyType`) to the +//! case of the source (e.g. `my-field`, `MY_FIELD`). // See https://users.rust-lang.org/t/psa-dealing-with-warning-unused-import-std-ascii-asciiext-in-today-s-nightly/13726 #[allow(deprecated, unused_imports)]