Add more details contrasting fromString and jsonParser

[milesfrain]

Description of the change

I recently found fromString when searching pursuit for String -> Json, and misunderstood how it's different from jsonParser. I assumed jsonParser just frontloads some error-checking that would otherwise be handled by decodeJson. This change adds some clarifying details.

Checklist:

Is changelog necessary for a documentation edit?

• Added the change to the changelog's "Unreleased" section with a link to this PR and your username

Not applicaple

• Linked any existing issues or proposals that this pull request should close
• Updated or added relevant documentation in the README and/or documentation directory
• Added a test for the contribution (if applicable)

[thomashoneyman]

Is changelog necessary for a documentation edit?

Not necessary, but welcome. Usually it'd go in the "Other improvements: " section under "Docs: ".

[thomashoneyman]

Would this be clearer if it said "Construct a Json string from a String value" to make it clear it's just producing a string, and not bonafide JSON with strings, numbers, objects, etc.?

[milesfrain]

"Json string" makes me think it produces the string representation of the json contents - like what you'd get from stringify.
What about changing to: "Construct the Json representation of a String value"?
I feel like the output is still bona fide JSON, even if it's very simple JSON in this case.
Also, if we change that first line, we should probably change all the other fromX docs.

[thomashoneyman]

I'm happy with that phrasing. And you're right, it's still bona fide JSON.

[thomashoneyman]

I think this just produces a string, not an object -- unless 'JSON object' can mean any JSON, not just objects.

[milesfrain]

I think from JavaScript's perspective, a string is also technically an object. Really, it seems that everything is an object, which is why we can apply these instance methods:

"hello".charAt(3) // "l"

z = 1.234567
z.toPrecision(3) // "1.23"
typeof z // "number"

However, the docs state that String, Number, etc. are not Object but primitives which by definition have no methods.

a primitive (primitive value, primitive data type) is data that is not an object and has no methods. There are 6 primitive data types: string, number, bigint, boolean, undefined, and symbol.

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures
https://developer.mozilla.org/en-US/docs/Glossary/Primitive

So I don't know what explains this inconsistency with the definitions of objects vs primitives and observed behavior. Are the docs incorrect? Is there some magic coercion/casting happening?

Back to JSON, the acronym also suggests that you always get an object (perhaps in the "everything is an object" sense), even if it's not key-value Object data (which has nothing to do with JS's "has methods" definition of Object - I'd rather see this named as dict or map when referring to json data). But I see how writing "object" perpetuates confusion, so I'd be up for rewriting as something like the following:

Note that this function only produces Json containing

Not sure about the exact phrasing, since it sounds pretty weird if you substitute with another type, e.g. "produces Number containing".

In an alternate universe, we'd be working with JSAN "JavaScript Array Notation", which I'd argue is no worse than the current name.

[thomashoneyman]

Yea, I'm thinking here about object in the data sense (map, dict, etc.), not object in the object-oriented programming sense. I think of JSON as being comprised of strings, numbers, booleans, arrays, objects, and null, which I believe is a common way to think of it, in which case referring to an array as an 'object' would confuse me a little.

Note that this function only produces Json containing

I think this is fine phrasing.

[thomashoneyman]

Suggested change

	-- | This function does NOT convert the `String` encoding of a JSON object to `Json` - For that
	-- | This function does NOT parse a string of JSON data into the equivalent `Json` -- for that

[thomashoneyman]

I'm a little wary of using the term 'object' here as it may lead a reader to believe this only applies to literal objects

[thomashoneyman]

Forgot to mention this, but I'd like to take out this line:

These "fromX" functions are often used to build-up JSON objects manually, as opposed to using encodeJson.

as there are more libraries for working with JSON than argonaut-codecs (even though it's the one bundled in to the 'argonaut ecosystem') and this library is more of a common base JSON type and utility functions for any other JSON libraries to work with.