Reformat docs; minor fixes

[ggleyzer]

While using JsonPointer API I noticed that some of the docs are formatted with a style different from other classes in this package. This is a trivial change - put there as a draft for JK to review two suspicious places in the code

[thegridman]

Here we are merging value into a new JsonObject so we may as well do it in place (hence the True argument). There is no point doing a copy if the inPlace parameter is False.

Also, I think line 31 is wrong, but I cannot add a comment to it on that line. I suspect it should be return merge(target, patch, inPlace);

[ggleyzer]

Hmm... looking closer into the
private Doc merge(Doc doc, Doc patch, Boolean inPlace = False)
implementation I realized, that inPlace argument is not used for anything but a recursive call to itself. The actual value affects absolutely nothing.

[thegridman]

Ah, it appears to always be doing an in-place merge, i.e modifying the target directly. Maybe that needs fixing.

[ggleyzer]

Not just that; the "inPlace" flag is not used for anything (e.g. ListMap construction)

[thegridman]

Right, it can be removed.

[ggleyzer]

Hmm... but if we remove it, then what is the point of calling this method? Don't we lose the value?

[thegridman]

So you can merge one json object into another, or one json array into another, but you cannot merge anything into a primitive. So if the target field is a primitive, it is basically just replaced with the value being merged in.

e.g. If I have

{"foo": 1234}

so "foo" is a primitive number field. The I want to merge the array [1, 2, 3, 4] into field "foo" I end up with

{"foo": [1, 2, 3, 4]}

If "foo" was an array

{"foo": [9, 8, 7]}

and I did the same merge then I believe I would get

{"foo": [9, 8, 7, 1, 2, 3, 4]}

[thegridman]

And, yes we lose the original value if it was a primitive

[ggleyzer]

Oh... I got confused by the doc then. The method doc says:

Deeply merge a `Primitive` value into this builder. 
...
@param doc   the value to merge the primitive into

So I thought the current value is supposed to be replaced by the primitive. I think it needs to be improved

[thegridman]

I have submitted some updates.

• I cleaned up the method docs in JsonBuilder.x as I think they were incorrect and certainly not clear.
• I have refactored the merge code in JsonMergePatch.x to work as described in the RFC. I added some tests using examples in the RFC.
• There are two TODO JK comments in the merge method in JsonMergePatch.x that need resolving

[ggleyzer]

Looks good!