@@ -28,20 +28,22 @@ typedef struct
28// Convention: if slen can be -1 for nul-terminated, or given explicitly
28// Convention: if slen can be -1 for nul-terminated, or given explicitly
30// Parse a document, returns a potentially invalid document - use document_error to check
30// Parse a document, returns a potentially invalid document - use document_error to check
31−// Must use document_free to release the memory.
31+// Must use document_free to release the memory (even if invalid).
32+// The string must be nul terminated, e.g. slen != -1 ==> slen[0]
32document* document_parse(char* s, int slen);
33document* document_parse(char* s, int slen);
34// Free the memory returned from document_parse.
35// Free the memory returned from document_parse.
35void document_free(document* d);
36void document_free(document* d);
37−// generate a fresh string with the same semantics as the node
38+// Generate a fresh string with the same semantics as the node.
38−// requires an input buffer, returns the size of the rendered document
39+// Requires an input buffer, returns the size of the rendered document.
40+// Requires the string passed to document_parse to be valid.
39int node_render(document* d, node* n, char* buffer, int length);
41int node_render(document* d, node* n, char* buffer, int length);
41−// return either NULL (successful parse) or the error message
43+// Return either NULL (successful parse) or the error message.
42char* document_error(document* d);
44char* document_error(document* d);
44−// return the root node of the document - imagine the document is wrapped in <>$DOC</> tags
46+// Return the root node of the document - imagine the document is wrapped in <>$DOC</> tags.
45node* document_node(document* d);
47node* document_node(document* d);
47// List all items within a node
49// List all items within a node
@@ -49,5 +51,6 @@ node* node_children(document* d, node* n, int* res);
49attr* node_attributes(document* d, node* n, int* res);
51attr* node_attributes(document* d, node* n, int* res);
51// Search for given strings within a node, note that prev may be NULL
53// Search for given strings within a node, note that prev may be NULL
54+// Requires the string passed to document_parse to be valid.
52node* node_childBy(document* d, node* parent, node* prev, char* s, int slen);
55node* node_childBy(document* d, node* parent, node* prev, char* s, int slen);
53attr* node_attributeBy(document* d, node* n, char* s, int slen);
56attr* node_attributeBy(document* d, node* n, char* s, int slen);