[elpa] externals/graphql f5660677d9 35/56: Add documentation

[ELPA Syncer]

branch: externals/graphql
commit f5660677d9d925e6066e724c8b9b3e0bf81eae26
Author: Sean Allred <code@seanallred.com>
Commit: Sean Allred <code@seanallred.com>

    Add documentation
---
 README.md  | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 graphql.el |   3 +-
 2 files changed, 105 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 19113d139c..46d253ef9c 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,107 @@
-GraphQL.el
-==========
+# GraphQL.el
 
-GraphQL.el provides a set of generic functions for interacting with
-GraphQL web services.
+GraphQL.el provides a set of generic functions for interacting with GraphQL 
web services.
 
 See also the following resources:
-- [GraphQL language 
service](https://github.com/graphql/graphql-language-service) and 
[`lsp-mode`](https://github.com/emacs-lsp/lsp-mode)
-- [`graphql-mode`](https://github.com/davazp/graphql-mode)
-- [This brief overview of GraphQL syntax](http://graphql.org/learn)
+- [GraphQL language service][graph-lsp] and [`lsp-mode`][el-lsp]
+- [`graphql-mode`][graphql-mode]
+- [This brief overview of GraphQL syntax][graphql]
+
+[graph-lsp]: https://github.com/graphql/graphql-language-service
+[el-lsp]: https://github.com/emacs-lsp/lsp-mode
+[graphql-mode]: https://github.com/davazp/graphql-mode
+[graphql]: http://graphql.org/learn
+
+## Syntax Overview
+Two macros are provided to express GraphQL *queries* and *mutations*:
+- `graphql-query` encodes the graph provided under a root `(query ...)` node.
+- `graphql-mutation` encodes the graph provided under a root `(mutation ...)` 
node.
+Both macros allow special syntax for query/mutation parameters if this is 
desired; see the docstrings for details.  I will note that backtick notation 
usually feels more natural in Lisp code.
+
+### Basic Queries
+The body of these macros is the graph of your query/mutation expressed in a 
Lispy DSL.  Generally speaking, we represent fields as symbols and edges as 
nested lists with the edge name being the head of that list.  For example,
+```emacs-lisp
+(graphql-query
+ (myField1 myField2 (myEdges (edges (node myField3)))))
+```
+will construct a query that retrieves `myField1`, `myField2`, and `myField3` 
for every node in `myEdges`.  The query is returned as a string without any 
unnecessary whitespace (i.e., formatting) added.
+
+## Following Edges
+Multiple edges can of course be followed.  Here's an example using GitHub's 
API:
+```emacs-lisp
+(graphql-query
+ ((viewer login)
+  (rateLimit limit cost remaining resetAt)))
+```
+
+## Passing Arguments
+Usually, queries need explicit arguments.  We pass them in an alist set off by 
the `:arguments` keyword:
+``` emacs-lisp
+(graphql-query
+ ((repository
+   :arguments ((owner . "github")
+               (name . ($ repo)))
+   (issues :arguments ((first . 20)
+                       (states . [OPEN CLOSED]))
+           (edges
+            (node number title url id))))))
+```
+As you can see, strings, numbers, vectors, symbols, and variables can all be 
given as arguments.  The above evaluates to the following (formatting added):
+``` graphql
+query {
+  repository (owner: "github", name: $repo) {
+    issues (first: 20, states: [OPEN, CLOSED]) {
+      edges {
+        node {
+          number title url id
+        }
+      }
+    }
+  }
+}
+```
+Objects as arguments work, too, though practical examples seem harder to come 
by:
+
+``` emacs-lisp
+(graphql-query
+ ((object :arguments ((someVariable . ((someComplex . "object")
+                                       (with . ($ complexNeeds))))))))
+```
+gives
+``` graphql
+query {
+  object (
+    someVariable: {
+      someComplex: "object",
+      with: $complexNeeds
+    }
+  )
+}
+```
+
+## Working with Responses
+- `graphql-simplify-response-edges`
+  Simplify structures like
+
+      (field
+       (edges
+        ((node node1values...))
+        ((node node2values...))))
+
+  into `(field (node1values) (node2values))`.
+
+## Keyword Reference
+- `:arguments`
+  Pass arguments to fields as an alist of parameters (as symbols) to values.  
See `graphql--encode-argument-value`.
+- `:op-name`, `:op-params`
+  Operation name/parameters.  Given to top-level *query* or *mutation* 
operations for later re-use.  You should rarely (if ever) need to supply these 
yourself; the `graphql-query` and `graphql-mutation` macros give you natural 
syntax to do this.
+
+## Planned
+- `:as` keyword for [aliases][graphql-alias] (`graphql-encode`).
+- `$` qualifier for [variables][graphql-variable] (`graphql--encode-object`)
+- `...` qualifier for [fragments][graphql-fragment] and [inline 
fragments][graphql-ifragment] (`graphql--encode-object`)
+
+[graphql-alias]: http://graphql.org/learn/queries/#aliases
+[graphql-variable]: http://graphql.org/learn/queries/#variables
+[graphql-fragment]: http://graphql.org/learn/queries/#fragments
+[graphql-ifragment]: http://graphql.org/learn/queries/#inline-fragments
diff --git a/graphql.el b/graphql.el
index 78a0ffa726..7b0fb57d83 100644
--- a/graphql.el
+++ b/graphql.el
@@ -124,14 +124,13 @@ parameter."
            (name (alist-get :op-name keys))
            (params (alist-get :op-params keys))
            (arguments (alist-get :arguments keys))
-           ;; TODO `:as' keyword for http://graphql.org/learn/queries/#aliases
            (fields (cdr-safe graph)))
        (concat
         (graphql--encode-object object)
         (when name
           (format " %S" name))
         (when arguments
-          ;; Format arguments "key:value, ..."
+          ;; Format arguments "key:value,key:value,..."
           (format "(%s)"
                   (mapconcat #'graphql--encode-argument-spec arguments ",")))
         (when params