Add some docs

[hdgarrood]

No description provided.

[garyb]

Really nicely explained, good work. Perhaps @robkuz can give some thoughts too, in case there's anything else that isn't obvious in here. Looks great to me though!

[hdgarrood]

Thanks :)

I think it's probably worth adding a small section that says something like "but I just want to serialize and deserialize my types!" and points to argonaut-codecs at some point too, but I was intending to address that later, perhaps together with docs for argonaut-codecs. It might be the case that people don't need to know very much about this library to be able to use argonaut-codecs.

[robkuz]

I like this opening - it sets the mindset the reader should have.

Alas I would name the data constructors differently as there a indeed types with names you are using here. Yes I know its only type synonyms yet it could easily confuse when you look into Pursuit and find exactly those types.
What about JSNull, JSBoolean ... Or even better NullWrapper, BooleanWrapper ...

[hdgarrood]

The constructor names do correspond exactly to the real types which have those names, though, so I think it makes sense to use the same names. It does also say that Argonaut does not use this approach in the next paragraph.

[hdgarrood]

I pushed a new commit with the following improvements:

• Define the whole hypothetical ADT in the first section; we nearly had all the cases covered anyway.
• Fix mixups of JSON.stringify and JSON.parse.
• Go into a little more detail about the JNumber, JString, JArray types.
• Mention the (previously forgotten) other way of introducing Json into your program: parsing it from a string!
• Add another key to the JSON object in the construction functions example, so that we have more than one key and therefore have a reason to not use jsonSingletonObject.
• Talk more about the type of foldJson, and how it is like a case ... of expression.

I did consider putting foldJson last, but it's the fundamental function for matching on Json values, so I think it's best that the section reflects this, by mentioning it first and having it occupy the majority of that section.

[hdgarrood]

I think this will do for now. I might come back to this later and write a fuller example as @robkuz suggested, but I am starting to suspect that the effort would be better spent on examples and docs for argonaut-codecs instead.

[kritzcreek]

Amazing work! Reading the docs really helped me understand what's going on, especially around the foldXXX. Thank you

[hdgarrood]

You're welcome :)