Parse some more of the document. The string s is a buffer
containing part (or perhaps all) of the document. The number of bytes of s
that are part of the document is indicated by len. This means
@@ -1112,12 +1113,40 @@ memory that s points at, then a memory fault is likely. The
isFinal parameter informs the parser that this is the last
piece of the document. Frequently, the last piece is empty (i.e.
len is zero.)
+
If a parse error occurred, it returns XML_STATUS_ERROR.
Otherwise it returns XML_STATUS_OK value.
Note that regardless of the return value, there is no guarantee that all
provided input has been parsed; only after the
concluding call will all handler callbacks and parsing errors have
happened.
+
+Simplified, XML_Parse can be considered a convenience wrapper
+that is pairing calls
+to XML_GetBuffer
+and XML_ParseBuffer
+(when Expat is built with macro XML_CONTEXT_BYTES
+defined to a positive value, which is both common and default).
+XML_Parse is then functionally equivalent to calling
+XML_GetBuffer,
+memcpy, and
+XML_ParseBuffer.
+
+To avoid double copying of the input, direct use of functions
+XML_GetBuffer and
+XML_ParseBuffer is advised
+for most production use, e.g.
+if you're using read or similar functionality to fill your
+buffers, fill directly into the buffer from
+XML_GetBuffer,
+then parse with XML_ParseBuffer.
+