Document a bunch of things

Also enable #[deny(missing_docs)] on the codegen crate.

Author: tomhoule

CHANGELOG.md

@@ -50,7 +50,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - For several classes of items that we generate, we only generate those that are actually used by the query. This way, you do not need to define mappings for _every_ scalar in the schema you are querying - even for small queries - anymore. This also improves compile times a lot in some scenarios. (#116 - thanks @mathstuf!)
 
-- Basic support for fragments on interfaces
+- Basic support for fragments on interfaces. See #137 for what is not supported yet.
 
 ### Fixed
 

graphql_client_codegen/src/attributes.rs

@@ -1,6 +1,7 @@
 use failure;
 use syn;
 
+/// Extract an configuration parameter specified in the `graphql` attribute.
 pub fn extract_attr(ast: &syn::DeriveInput, attr: &str) -> Result<String, failure::Error> {
     let attributes = &ast.attrs;
     let attribute = attributes

graphql_client_codegen/src/deprecation.rs

@@ -4,16 +4,23 @@ use syn;
 
 static DEPRECATION_ERROR: &'static str = "deprecated must be one of 'allow', 'deny', or 'warn'";
 
+/// Whether an item is deprecated, with context.
 #[derive(Debug, PartialEq, Hash, Clone)]
 pub enum DeprecationStatus {
+    /// Not deprecated
     Current,
+    /// Deprecated
     Deprecated(Option<String>),
 }
 
+/// The available deprecation startegies.
 #[derive(Debug, PartialEq)]
 pub enum DeprecationStrategy {
+    /// Allow use of deprecated items in queries, and say nothing.
     Allow,
+    /// Fail compilation if a deprecated item is used.
     Deny,
+    /// Allow use of deprecated items in queries, but warn about them (default).
     Warn,
 }
 
@@ -23,6 +30,7 @@ impl Default for DeprecationStrategy {
     }
 }
 
+/// Get the deprecation from a struct attribute in the derive case.
 pub fn extract_deprecation_strategy(
     ast: &syn::DeriveInput,
 ) -> Result<DeprecationStrategy, failure::Error> {

graphql_client_codegen/src/fragments.rs

@@ -3,15 +3,21 @@ use query::QueryContext;
 use selection::Selection;
 use std::cell::Cell;
 
+/// Represents a fragment extracted from a query document.
 #[derive(Debug, PartialEq)]
 pub struct GqlFragment {
+    /// The name of the fragment, matching one-to-one with the name in the GraphQL query document.
     pub name: String,
+    /// The `on` clause of the fragment.
     pub on: String,
+    /// The selected fields.
     pub selection: Selection,
+    /// Whether the fragment
     pub is_required: Cell<bool>,
 }
 
 impl GqlFragment {
+    /// Generate all the Rust code required by the fragment's selection.
     pub(crate) fn to_rust(&self, context: &QueryContext) -> Result<TokenStream, ::failure::Error> {
         let derives = context.response_derives();
         let name_ident = Ident::new(&self.name, Span::call_site());

graphql_client_codegen/src/interfaces.rs

@@ -12,13 +12,17 @@ use unions::union_variants;
 #[derive(Debug, Clone, PartialEq)]
 pub struct GqlInterface {
     pub description: Option<String>,
+    /// The set of object types implementing this interface.
     pub implemented_by: HashSet<String>,
+    /// The name of the interface. Should match 1-to-1 to its name in the GraphQL schema.
     pub name: String,
+    /// The interface's fields. Analogous to object fields.
     pub fields: Vec<GqlObjectField>,
     pub is_required: Cell<bool>,
 }
 
 impl GqlInterface {
+    /// filters the selection to keep only the fields that refer to the interface's own.
     fn object_selection(&self, selection: &Selection) -> Selection {
         Selection(
             selection
@@ -34,6 +38,7 @@ impl GqlInterface {
         )
     }
 
+    /// Create an empty interface. This needs to be mutated before it is useful.
     pub(crate) fn new(name: Cow<str>, description: Option<&str>) -> GqlInterface {
         GqlInterface {
             description: description.map(|d| d.to_owned()),
@@ -44,6 +49,7 @@ impl GqlInterface {
         }
     }
 
+    /// The generated code for each of the selected field's types. See [shared::field_impls_for_selection].
     pub(crate) fn field_impls_for_selection(
         &self,
         context: &QueryContext,
@@ -58,6 +64,7 @@ impl GqlInterface {
         )
     }
 
+    /// The code for the interface's corresponding struct's fields.
     pub(crate) fn response_fields_for_selection(
         &self,
         context: &QueryContext,
@@ -73,6 +80,7 @@ impl GqlInterface {
         )
     }
 
+    /// Generate all the code for the interface.
     pub(crate) fn response_for_selection(
         &self,
         query_context: &QueryContext,

graphql_client_codegen/src/lib.rs

@@ -1,4 +1,9 @@
 #![recursion_limit = "512"]
+#![deny(missing_docs)]
+
+//! Crate for internal use by other graphql-client crates, for code generation.
+//!
+//! It is not meant to be used directly by users of the library.
 
 #[macro_use]
 extern crate failure;
@@ -19,11 +24,14 @@ extern crate quote;
 
 use proc_macro2::TokenStream;
 
+/// Derive-related code. This will be moved into graphql_query_derive.
 pub mod attributes;
-pub mod codegen;
+mod codegen;
+/// Deprecation-related code
 pub mod deprecation;
-pub mod introspection_response;
-pub mod query;
+mod introspection_response;
+mod query;
+/// Contains the [Schema] type and its implementation.
 pub mod schema;
 
 mod constants;
@@ -55,9 +63,13 @@ lazy_static! {
         CacheMap::default();
 }
 
+/// Used to configure code generation.
 pub struct GraphQLClientDeriveOptions {
+    /// Name of the operation we want to generate code for. If it does not match, we default to the first one.
     pub struct_name: String,
+    /// Comma-separated list of additional traits we want to derive.
     pub additional_derives: Option<String>,
+    /// The deprecation strategy to adopt.
     pub deprecation_strategy: Option<deprecation::DeprecationStrategy>,
 }
 
@@ -66,6 +78,7 @@ pub(crate) struct FullResponse<T> {
     data: T,
 }
 
+/// Generates the code for a Rust module given a query, a schema and options.
 pub fn generate_module_token_stream(
     query_path: std::path::PathBuf,
     schema_path: std::path::PathBuf,

graphql_client_codegen/src/schema.rs

@@ -10,23 +10,24 @@ use scalars::Scalar;
 use std::collections::{BTreeMap, BTreeSet};
 use unions::GqlUnion;
 
-pub const DEFAULT_SCALARS: &[&str] = &["ID", "String", "Int", "Float", "Boolean"];
+pub(crate) const DEFAULT_SCALARS: &[&str] = &["ID", "String", "Int", "Float", "Boolean"];
 
+/// Intermediate representation for a parsed GraphQL schema used during code generation.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Schema {
-    pub enums: BTreeMap<String, GqlEnum>,
-    pub inputs: BTreeMap<String, GqlInput>,
-    pub interfaces: BTreeMap<String, GqlInterface>,
-    pub objects: BTreeMap<String, GqlObject>,
-    pub scalars: BTreeMap<String, Scalar>,
-    pub unions: BTreeMap<String, GqlUnion>,
-    pub query_type: Option<String>,
-    pub mutation_type: Option<String>,
-    pub subscription_type: Option<String>,
+    pub(crate) enums: BTreeMap<String, GqlEnum>,
+    pub(crate) inputs: BTreeMap<String, GqlInput>,
+    pub(crate) interfaces: BTreeMap<String, GqlInterface>,
+    pub(crate) objects: BTreeMap<String, GqlObject>,
+    pub(crate) scalars: BTreeMap<String, Scalar>,
+    pub(crate) unions: BTreeMap<String, GqlUnion>,
+    pub(crate) query_type: Option<String>,
+    pub(crate) mutation_type: Option<String>,
+    pub(crate) subscription_type: Option<String>,
 }
 
 impl Schema {
-    pub fn new() -> Schema {
+    pub(crate) fn new() -> Schema {
         Schema {
             enums: BTreeMap::new(),
             inputs: BTreeMap::new(),
@@ -40,7 +41,7 @@ impl Schema {
         }
     }
 
-    pub fn ingest_interface_implementations(
+    pub(crate) fn ingest_interface_implementations(
         &mut self,
         impls: BTreeMap<String, Vec<String>>,
     ) -> Result<(), failure::Error> {