Reference promises for resolve func

[chrisbolin]

In response to #27 and SO questions. I don't believe there is "official" documentation (besides in issues and tests) of Promise support in the resolve function. Totally willing to be wrong :)

[coveralls]

Coverage remained the same at 99.408% when pulling a747503 on chrisbolin:patch-1 into 57d71e1 on graphql:master.

[leebyron]

Our "official" documentation is pretty poor anyhow, but thanks for helping us move to correct that!

[chrisbolin]

@leebyron I could help with graphql-js docs. are there specific topics / issues you'd like to document?

[leebyron]

That would be awesome! I'd love any help you're willing to provide.

Here's my rough wish-list for improved documentation:

1. More in-depth prose and examples on using this library. http://graphql.org/docs/getting-started/ is a start, but there's not a lot of help beyond this for setting up anything more than this simple schema.
2. General higher quality version of all the "api reference" docs, filling in missing pieces and better examples and prose for each. It would be really awesome if we could automatically generate good documentation from the codebase itself. We've worked hard to maintain good flow type definitions and doc blocks within the codebase, but a reference docs site would be much easier to navigate.
3. Move the "api reference" documentation for graphql-js out of https://github.com/graphql/graphql.github.io/ (graphql.org) and into this repo so it's easier to maintain in sync with the rest of this codebase. (I'll probably eventually tackle this since it requires some gh-pages & travis-ci setup)

[chrisbolin]

Quick philosophical question: where do docs about graphql-js the library go vs. GraphQL the spec? It sounds like you'd like graphql.org to provide both, correct?

[leebyron]

The current reality is that they exist as a sub-section of graphql.org - http://graphql.org/docs/api-reference-graphql/

Philosophically, graphql.org really should be about general GraphQL usage not specific to any one host language. However it should still have ample links out to GraphQL implementations including most importantly this one since it's the reference implementation.

I think the appropriate end state is that this repo host a subdir on graphql.org, so graphql.org/graphql-js can be 100% focused on graphql-js usage.