DocumentManager.newPatchBuilder javadoc is probably wrong

[kcoleman-marklogic]

I noticed the javadoc for DocumentManager.newPatchBuilder looks quite wrong, but I'm not conversant enough with the interfaces to know for sure. I'm talking about this guy:

http://docs.marklogic.com/javadoc/client/com/marklogic/client/document/DocumentManager.html#newPatchBuilder(com.marklogic.client.io.Format)

(That's a 7.0 link, but it's the same javadoc in 8.0).

• Why does it say it’s for building metadata patches? I think MetadataPatchBuilder is just the superclass and its really for both content and metadata.
• Why does it have a param called pathFormat of type com.marklogic.client.io.Format (text, xml, binary, json) described as “whether the patch specifies metadata with JSON or XML paths”?

Patches don’t just use paths for metadata, and it isn’t “JSON or XML paths”. It’s JSONPath or XPath, even in 7.0. Secondly, what is the new DocumentPatchBuilder.Language for, if not choosing between JSONPath and XPath?

Could this be meant to be patchFormat, not pathFormat? That is, you generally build a JSON patch for a JSON document and an XML patch for an XML document, though it’s possible to override. It has nothing to do with whether you use JSONPath or XPath to address the items being patched. The patch builder would certainly need to know this, and it's more consistent with the parameter type.

[kcoleman-marklogic]

Thanks, Sam. I think there's a slight typo in the param description, where it says "specifies with":
"whether the patch specifies with JSON or XML paths"

Maybe just "uses" or "expects" instead of "specifies with"?

I also think it'd be more useful to call a spade a spade and call it JSONPath and XPath so the user can actually find information about the format. There's no such thing as a "JSON path" or an "XML path", IMO. Maybe something like:

the patch path language. Set to JSON for JSONPath and XML for XPath.