Add a bunch more documentation (and rewrite README) #86
Conversation
benjaminjkraft
requested review from
aberkan,
dnerdy,
jvoll,
mahtabsabet and
MiguelCastillo
benjaminjkraft
force-pushed
the
benkraft.docs-2
branch
2 times, most recently
from
d74921e to
2ecc3ae
Compare
benjaminjkraft
force-pushed
the
benkraft.docs-3
branch
from
6709c1e to
7289b85
Compare
In this commit, I add a bunch more documentation of how to use genqlient, including a getting started guide, and a FAQ that also acts as a how-to shaped index of common configuration options and extension points. Much of this is adapted from the internal doc I wrote at Khan, or reorganized from what was in the README. Speaking of which, now that there are better places for all the details, I rewrote the README to be a bit more of an overview and index of other documentation. (For now I left the "unmaintained" notes, which I'll remove fairly soon once all our ducks are in a row.) Fixes #26. Issue: #26 Test plan: make check, read the docs Reviewers: marksandstrom, adam, miguel, mahtab, jvoll
This is something that came up at Khan; we decided that just binding to `int` is actually the right thing, but there are other options. Fixes #39.
benjaminjkraft
force-pushed
the
benkraft.docs-3
branch
from
7289b85 to
e8d24f1
Compare
| myGreatName: myField | ||
| } | ||
| ``` | ||
| and genqlient will generate a Go field `MyGreatName string`. Note that the alias will always be uppercased, to ensure the field is visible to the Go JSON library. |
There was a problem hiding this comment.
This is assuming that myField was already a string, right?
There was a problem hiding this comment.
Ah, yeah, I'll add some notes to that effect. Or maybe just call it myString!
| # @genqlient(pointer: true) | ||
| arg: String, | ||
| ) { | ||
| # @genqlient(pointer: true) |
There was a problem hiding this comment.
Can we also put # @genqlient(pointer: true) on the first line to apply it to everything in the query, similar to the previous omitempty example?
There was a problem hiding this comment.
Yes! Will mention.
| genqlient will generate the following types: | ||
|
|
||
| ```go | ||
| type GetBooksFavoriteBook interface { |
There was a problem hiding this comment.
This might be documented elsewhere, but how does genqlient generate the FavouriteBook part of the name?
There was a problem hiding this comment.
Yep it's below! I can mention it.
docs/FAQ.md
Outdated
| ```graphql | ||
| # This query gets the current user. | ||
| # | ||
| # @genqlient(...) |
There was a problem hiding this comment.
what is supposed to go inside @genqlient(...)?
There was a problem hiding this comment.
Ah, this is just to show that if you have a genqlient directive, you can put it after the documentation. I'll clarify.
Summary:
In this commit, I add a bunch more documentation of how to use
genqlient, including a getting started guide, and a FAQ that also acts
as a how-to shaped index of common configuration options and extension
points. Much of this is adapted from the internal doc I wrote at Khan,
or reorganized from what was in the README. Speaking of which, now that
there are better places for all the details, I rewrote the README to be
a bit more of an overview and index of other documentation. (For now I
left the "unmaintained" notes, which I'll remove fairly soon once all
our ducks are in a row.)
Fixes #26, #39.
Issue: #26
Issue: #39
Test plan:
make check, read the docs