Reorganize the README

Author: tomhoule

README.md

@@ -4,56 +4,69 @@
 [![docs](https://docs.rs/graphql_client/badge.svg)](https://docs.rs/graphql_client/0.0.1/graphql_client/)
 [![crates.io](https://img.shields.io/crates/v/graphql_client.svg)](https://crates.io/crates/graphql_client)
 
-Derive Rust code to safely and ergonomically manipulate GraphQL queries.
+A typed, ergonomic GraphQL client library for Rust.
 
-This library does not provide any networking, caching or other client functionality yet, it is just meant to make it easy to interact with a GraphQL query and the corresponding response in a strongly typed way. Making a request can be as simple as this:
+## Getting started
+
+In order to provide precise types for a response, graphql_client needs to read the query and the schema at compile-time.
+
+This is achieved through a procedural macro, as in the following snippet:
 
 ```rust
+// The paths are relative to the directory where your `Cargo.toml` is located.
+// Both json and the GraphQL schema language are supported as sources for the schema
 #[derive(GraphQLQuery)]
 #[graphql(
-    // The paths are relative to the directory where your `Cargo.toml` is located.
+    schema_path = "src/graphql/schema.json",
     query_path = "src/graphql/queries/my_query.graphql",
-    schema_path = "src/graphql/schema.json"
 )]
-struct MyQuery;
+pub struct MyQuery;
 ```
 
+The `derive` will generate a module named `my_query` in this example - the name is the struct's name, but in snake case.
+
+That module contains all the struct and enum definitions necessary to deserialize a response to that query.
+
+The root type for the response is named `ResponseData`. The GraphQL response will take  the form of a `GraphQLResponse<ResponseData>` (the [GraphQLResponse](https://docs.rs/graphql_client/latest/graphql_client/struct.GraphQLResponse.html) type is always the same).
+
+The module also contains a struct called `Variables` representing the variables expected by the query.
+
+[A full example is available](https://github.com/tomhoule/graphql-client/tree/master/examples/example_module), including [rustdoc output](https://www.tomhoule.com/docs/example_module/).
+
+NOTE: `serde` and `serde_derive` need to be imported in the current crate with `extern crate`.
+
+For convenience, the [GraphQLQuery trait](https://docs.rs/graphql_client/latest/graphql_client/trait.GraphQLQuery.html), is implemented for the struct under derive, so it can be used this way:
+
 ```rust
 fn perform_my_query(variables: &my_query::Variables) -> Result<(), failure::Error> {
-    let body = MyQuery::expand(variables);
+    let request_body = MyQuery::expand(variables);
     let client = reqwest::Client::new();
-    let mut res: HttpResponse<graphql_client::Response<my_query::ResponseData>> = client.post("/graphql").json(&body).send()?;
-    println!("{:#?}", res.text());
+    let mut res = client.post("/graphql").json(&request_body).send()?;
+    let response_body: GraphQLResponse<my_query::ResponseData> = res.json()?;
+    println!("{:#?}", response_body);
     Ok(())
 }
 ```
 
-The GraphQL schema language (`.graphql`) and `schema.json` are both supported as sources for the schema.
-
-`serde_derive` needs to be visible in the context of the `GraphQLQuery` derive (add it as an `extern crate`).
-
 ## Features
 
 - Strongly typed query variables
 - Strongly typed responses
 - Works in the browser (WebAssembly)
+- Supports GraphQL fragments, objects, unions, inputs, enums, custom scalars and input objects
 
-Integration with different HTTP libraries is planned, although building one yourself is trivial (just send the constructed request payload as JSON with a POST request to a GraphQL endpoint, modulo authentication).
+### Roadmap
 
-There is an embryonic CLI for downloading schemas - the plan is to make it something similar to `apollo-codegen`.
+A lot of desired features have been defined in issues.
 
-## What is generated?
+graphql_client does not provide any networking, caching or other client functionality yet. Integration with different HTTP libraries is planned, although building one yourself is trivial (just send the constructed request payload as JSON with a POST request to a GraphQL endpoint, modulo authentication).
 
-- A module named after the struct under derive, which contains:
-  - A `ResponseData` struct implementing `serde::Deserialize`
-  - A `Variables` struct meant to contain the variables expected by the query
-- An impl for the `GraphQLQuery` trait for the struct under derive
+There is an embryonic CLI for downloading schemas - the plan is to make it something similar to `apollo-codegen`.
 
-See the [example generated module](https://www.tomhoule.com/docs/example_module/) for more details.
 
 ## Examples
 
-See the examples directory in this project.
+See the examples directory in this repository.
 
 ## Code of conduct
 

src/lib.rs

@@ -1,3 +1,4 @@
+///! The top-level documentation resides on the [project README](https://github.com/tomhoule/graphql-client) at the moment.
 extern crate serde;
 #[macro_use]
 extern crate serde_derive;
@@ -7,6 +8,7 @@ extern crate graphql_query_derive;
 #[doc(hidden)]
 pub use graphql_query_derive::*;
 
+/// A convenience trait that can be used to build a GraphQL request body.
 pub trait GraphQLQuery<'de> {
     type Variables: serde::Serialize;
     type ResponseData: serde::Deserialize<'de>;
@@ -29,6 +31,9 @@ pub struct GraphQLError {
     pub path: String,
 }
 
+/// The generic shape taken by the responses of GraphQL APIs.
+///
+/// This will generally be used with the `ResponseData` struct from a derived module.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct GraphQLResponse<Data> {
     pub data: Option<Data>,