graphql.js custom scalar type docs are very vague

[msakrejda]

I was trying to create a custom scalar type by reading the docs, but what's there is very vague and confusing:

• What are the semantics of the three required functions? Only names are listed right now.
• The example doesn't compensate for the lack of descriptions, since it uses the same function for two of the fields
• The example type is strange: it... returns the value if odd and null otherwise? That seems like a completely fanciful type with no practical use. Perhaps a Date type would be more useful?

I think the GraphQL docs are fantastic overall, but this section was not clear at all.

[stubailo]

We have three examples with graphql-tools here: http://dev.apollodata.com/tools/graphql-tools/scalars.html

The syntax is a bit different, but the functions are the same. Perhaps we can move those docs to the graphql-js docs here.

[msakrejda]

Yes, I think that would be great. That page doesn't describe the semantics of these methods, though (except for some one-liner comments). A short blurb on that for each method would be really helpful.