Add API Use Case examples

[b2k]

Is your feature request related to a problem? Please describe.
The API Documentation lacks use-case examples for each of the Scalar Types.

For example, the DateTime scalar states that values are shifted to UTC. I'm assuming this means that a round-trip of a DateTime value would lose the original timezone offset. The implications of this shift is unclear in the documentation.

A scalar type that merely references an RFC also lacks clarity, such as the Currency data type. If I wanted to send 10 US Dollars as a currency scalar, what do I send? Do I send a float, an int or a string? For a string value, is it "$10.00" or "USD 10.0" or "USD10"?

Another issue is with the Duration type. What the heck is "P1W1DT13H23M34S"? I see there is a reference to an ISO standard, but no link. A link would be helpful, but an example that clarifies this would be better.

There are three Json types, Json, JsonObject and JsonLiteral, but which to use when isn't clear.

Describe the solution you'd like
Please add better descriptions that do not require visiting the ISO standards to gain a basic understanding of the Scalars. Also add use cases, showing example values of each type.

[ardatan]

• As described in the documentation, DateTime scalar sticks with UTC. This seems exist in the documentation
  

Also tests can give some idea;
https://github.com/Urigo/graphql-scalars/blob/master/tests/iso-date/DateTime.test.ts

• Currency scalar follows ISO-4217 as described in the website and the structure of currency codes can be found in the link and they are strings for sure.
  https://github.com/Urigo/graphql-scalars/blob/master/tests/Currency.test.ts

• ISO8601 is a standard you can easily find on Google :)
  https://en.wikipedia.org/wiki/ISO_8601#Durations
  And I see there is a short description in our website as well.
  

https://github.com/Urigo/graphql-scalars/blob/master/tests/iso-date/Duration.test.ts

• We have JSON and JSONObject and the difference is that one can take any JSON-compatible value including primitives while the other one can only take objects.

Thanks for your comments. We'd love to accept PRs and any more contributions to make this library better for everyone in the open source community.

[b2k]

This reinforces my point. I clearly had already read the documentation on DateTime and Duration.

Regarding the Duration type, I've been able to decipher the documentation, and I'm left wondering why a simple example is lacking. P1W1DT13H23M34S = 1 week, 1 day, 13 hours, 23 minutes and 34 seconds.. The description for it does not make this clear.

I will consider adding a few PRs once I become more familiar with GraphQL and scalar definitions. It would be nice to see a Moment scalar which preserves the original time zone.

[Urigo]

@b2k thanks for the feedback, we would love to see PRs for the docs and iterate together with you on them!