Ben Kraft
2eba9a2c30
## Summary: In this commit I reorganize much of our documentation into a new `docs` directory, where there will hopefully be more room to grow and to organize things in a user-friendly way. There's almost no net-new documentation, although of course it's a great time to review it anyway. In particular: - I moved the documentation for the `genqlient.yaml` config file into an example file instead of GoDoc (which now just points to the example file); I think this will be a lot clearer for casual users. - I moved the documentation for the `@genqlient` directive out of GoDoc and into a GraphQL schema file (since while it's a comment it's all real syntax), likewise, and made the `GenqlientDirective` type private (since there's now nothing useful to do with it). - I moved `DESIGN.md` and the logo into `docs/` (just to keep the toplevel a bit cleaner), and separated the Contributing section of the README into `docs/CONTRIBUTING.md` (which github will automatically link on various issue and PR pages). This leaves it so that: - README.md is the only documentation at the toplevel (and will become just the high-level introduction as I add more user docs to `docs/`) - GoDoc is only documentation for if you want to call genqlient programmatically (which is fairly limited as the API surface is quite small: it's now just Main, Generate, and Config, plus a constructor, a single method, and a bunch of fields on the latter) In future commits, I'll add some more new documentation to the `docs` directory. Issue: https://github.com/Khan/genqlient/issues/26 ## Test plan: make check (and read the docs) Author: benjaminjkraft Reviewers: jvoll, benjaminjkraft, aberkan, dnerdy, MiguelCastillo, mahtabsabet Required Reviewers: Approved By: jvoll Checks: ✅ Lint, ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Lint Pull Request URL: https://github.com/Khan/genqlient/pull/84
87 lines
3.2 KiB
GraphQL
87 lines
3.2 KiB
GraphQL
# The quasi-directive @genqlient is used to configure genqlient on a
|
|
# query-by-query basis.
|
|
#
|
|
# The syntax of the directive is just like a GraphQL directive (as defined
|
|
# below), except it goes in a comment on the line immediately preceding the
|
|
# field. (This is because GraphQL expects directives in queries to be defined
|
|
# by the server, not by the client, so it would reject a real @genqlient
|
|
# directive as nonexistent.)
|
|
#
|
|
# Directives may be applied to fields, arguments, or the entire query.
|
|
# Directives on the line preceding the query apply to all relevant nodes in
|
|
# the query; other directives apply to all nodes on the following line. (In
|
|
# all cases it's fine for there to be other comments in between the directive
|
|
# and the node(s) to which it applies.) For example, in the following query:
|
|
# # @genqlient(n: "a")
|
|
#
|
|
# # @genqlient(n: "b")
|
|
# #
|
|
# # Comment describing the query
|
|
# #
|
|
# # @genqlient(n: "c")
|
|
# query MyQuery(arg1: String,
|
|
# # @genqlient(n: "d")
|
|
# arg2: String, arg3: String,
|
|
# arg4: String,
|
|
# ) {
|
|
# # @genqlient(n: "e")
|
|
# field1, field2
|
|
# field3
|
|
# }
|
|
# the directive "a" is ignored, "b" and "c" apply to all relevant nodes in the
|
|
# query, "d" applies to arg2 and arg3, and "e" applies to field1 and field2.
|
|
directive genqlient(
|
|
|
|
# If set, this argument will be omitted if it's equal to its Go zero
|
|
# value, or is an empty slice.
|
|
#
|
|
# For example, given the following query:
|
|
# # @genqlient(omitempty: true)
|
|
# query MyQuery(arg: String) { ... }
|
|
# genqlient will generate a function
|
|
# MyQuery(ctx context.Context, client graphql.Client, arg string) ...
|
|
# which will pass {"arg": null} to GraphQL if arg is "", and the actual
|
|
# value otherwise.
|
|
#
|
|
# Only applicable to arguments of nullable types.
|
|
omitempty: Boolean
|
|
|
|
# If set, this argument or field will use a pointer type in Go. Response
|
|
# types always use pointers, but otherwise we typically do not.
|
|
#
|
|
# This can be useful if it's a type you'll need to pass around (and want a
|
|
# pointer to save copies) or if you wish to distinguish between the Go
|
|
# zero value and null (for nullable fields).
|
|
pointer: Boolean
|
|
|
|
# If set, this argument or field will use the given Go type instead of a
|
|
# genqlient-generated type.
|
|
#
|
|
# The value should be the fully-qualified type name to use for the field,
|
|
# for example:
|
|
# time.Time
|
|
# map[string]interface{}
|
|
# []github.com/you/yourpkg/subpkg.MyType
|
|
# Note that the type is the type of the whole field, e.g. if your field in
|
|
# GraphQL has type `[DateTime]`, you'd do
|
|
# # @genqlient(bind: "[]time.Time")
|
|
# (But you're not required to; if you want to map to some type DateList,
|
|
# you can do that, as long as its UnmarshalJSON method can accept a list
|
|
# of datetimes.)
|
|
#
|
|
# See bindings in genqlient.yaml for more details; this is effectively to a
|
|
# local version of that global setting and should be used with similar care.
|
|
# If set to "-", overrides any such global setting and uses a
|
|
# genqlient-generated type.
|
|
bind: String
|
|
|
|
) on
|
|
# genqlient directives can go almost anywhere, although some options are only
|
|
# applicable in certain locations as described above.
|
|
| QUERY
|
|
| MUTATION
|
|
| SUBSCRIPTION
|
|
| FIELD
|
|
| FRAGMENT_DEFINITION
|
|
| VARIABLE_DEFINITION
|