Merge pull request #1399 from derekdreery/more_docs

Some docs

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 to generate Rust code.
+
 use internals::attr;
 use internals::check;
 use internals::{Ctxt, Derive};
 use syn;
 use syn::punctuated::Punctuated;
 
+/// 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).
     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<Variant<'a>>),
     Struct(Style, Vec<Field<'a>>),
 }
 
+/// 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<Field<'a>>,
 }
 
+/// A field 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);
 

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,

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.
 
+//! 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)]
 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(),

serde_derive/src/internals/ctxt.rs

@@ -10,18 +10,29 @@ 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<Option<Vec<String>>>,
 }
 
 impl Ctxt {
+    /// 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.
     pub fn error<T: Display>(&self, msg: T) {
         self.errors
             .borrow_mut()
@@ -30,6 +41,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() {