From 712ebba754bda6a1d405ee06400433b07c4e9b2d Mon Sep 17 00:00:00 2001 From: John Mark Bell Date: Sat, 10 Jan 2009 17:38:42 +0000 Subject: Improve documentation of tree handler APIs. svn path=/trunk/hubbub/; revision=6019 --- include/hubbub/functypes.h | 175 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 157 insertions(+), 18 deletions(-) (limited to 'include/hubbub') diff --git a/include/hubbub/functypes.h b/include/hubbub/functypes.h index b525980..4280163 100644 --- a/include/hubbub/functypes.h +++ b/include/hubbub/functypes.h @@ -14,115 +14,254 @@ #include -/* Type of allocation function for hubbub */ +/** + * Type of allocation function for hubbub + * + * The semantics of this function are the same as for realloc(). + * + * \param ptr Pointer to object to reallocate, or NULL for a new allocation + * \param size Required length in bytes, or zero to free ::ptr + * \param pw Pointer to client data + * \return Pointer to allocated object, or NULL on failure + */ typedef void *(*hubbub_alloc)(void *ptr, size_t size, void *pw); /** * Type of token handling function + * + * \param token Pointer to token to handle + * \param pw Pointer to client data + * \return HUBBUB_OK on success, appropriate error otherwise. */ typedef hubbub_error (*hubbub_token_handler)( const hubbub_token *token, void *pw); /** * Type of parse error handling function + * + * \param line Source line on which error occurred + * \param col Column in ::line of start of erroneous input + * \param message Error message + * \param pw Pointer to client data */ typedef void (*hubbub_error_handler)(uint32_t line, uint32_t col, const char *message, void *pw); /** - * Type of tree comment node creation function + * Create a comment node + * + * \param ctx Client's context + * \param data String content of node + * \param result Pointer to location to receive created node + * \return 0 on success, 1 on failure. + * + * Postcondition: if successful, result's reference count must be 1. */ typedef int (*hubbub_tree_create_comment)(void *ctx, const hubbub_string *data, void **result); /** - * Type of tree doctype node creation function + * Create a doctype node + * + * \param ctx Client's context + * \param doctype Data for doctype node (name, public id, system id) + * \param result Pointer to location to receive created node + * \return 0 on success, 1 on failure. + * + * Postcondition: if successful, result's reference count must be 1. */ typedef int (*hubbub_tree_create_doctype)(void *ctx, const hubbub_doctype *doctype, void **result); /** - * Type of tree element node creation function + * Create an element node + * + * \param ctx Client's context + * \param tag Data for element node (namespace, name, attributes) + * \param result Pointer to location to receive created node + * \return 0 on success, 1 on failure. + * + * Postcondition: if successful, result's reference count must be 1. */ typedef int (*hubbub_tree_create_element)(void *ctx, const hubbub_tag *tag, void **result); /** - * Type of tree text node creation function + * Create a text node + * + * \param ctx Client's context + * \param data String content of node + * \param result Pointer to location to receive created node + * \return 0 on success, 1 on failure. + * + * Postcondition: if successful, result's reference count must be 1. */ typedef int (*hubbub_tree_create_text)(void *ctx, const hubbub_string *data, void **result); /** - * Type of tree node reference function + * Increase a node's reference count + * + * \param ctx Client's context + * \param node Node to reference + * \param 0 on success, 1 on failure. + * + * Postcondition: node's reference count is one larger than before */ typedef int (*hubbub_tree_ref_node)(void *ctx, void *node); /** - * Type of tree node dereference function + * Decrease a node's reference count + * + * \param ctx Client's context + * \param node Node to reference + * \param 0 on success, 1 on failure. + * + * Postcondition: If the node's reference count becomes zero, and it has no + * parent, and it is not the document node, then it is destroyed. Otherwise, + * the reference count is one less than before. */ typedef int (*hubbub_tree_unref_node)(void *ctx, void *node); /** - * Type of tree node appending function + * Append a node to the end of another's child list + * + * \param ctx Client's context + * \param parent The node to append to + * \param child The node to append + * \param result Pointer to location to receive appended node + * \return 0 on success, 1 on failure + * + * Postcondition: if successful, result's reference count is increased by 1 + * + * Important: *result may not == child (e.g. if text nodes got coalesced) */ typedef int (*hubbub_tree_append_child)(void *ctx, void *parent, void *child, void **result); /** - * Type of tree node insertion function + * Insert a node into another's child list + * + * \param ctx Client's context + * \param parent The node to insert into + * \param child The node to insert + * \param ref_child The node to insert before + * \param result Pointer to location to receive inserted node + * \return 0 on success, 1 on failure + * + * Postcondition: if successful, result's reference count is increased by 1 + * + * Important: *result may not == child (e.g. if text nodes got coalesced) */ typedef int (*hubbub_tree_insert_before)(void *ctx, void *parent, void *child, void *ref_child, void **result); /** - * Type of tree node removal function + * Remove a node from another's child list + * + * \param ctx Client context + * \param parent The node to remove from + * \param child The node to remove + * \param result Pointer to location to receive removed node + * \return 0 on success, 1 on failure + * + * Postcondition: if successful, result's reference count is increased by 1 */ typedef int (*hubbub_tree_remove_child)(void *ctx, void *parent, void *child, void **result); /** - * Type of tree node cloning function + * Clone a node + * + * \param ctx Client's context + * \param node The node to clone + * \param deep True to clone entire subtree, false to clone only the node + * \param result Pointer to location to receive clone + * \return 0 on success, 1 on failure + * + * Postcondition: if successful, result's reference count must be 1. */ typedef int (*hubbub_tree_clone_node)(void *ctx, void *node, bool deep, void **result); /** - * Type of child reparenting function + * Move all the children of one node to another + * + * \param ctx Client's context + * \param node The initial parent node + * \param new_parent The new parent node + * \return 0 on success, 1 on failure */ typedef int (*hubbub_tree_reparent_children)(void *ctx, void *node, void *new_parent); /** - * Type of parent node acquisition function + * Retrieve the parent of a node + * + * \param ctx Client context + * \param node Node to retrieve the parent of + * \param element_only True if the parent must be an element, false otherwise + * \param result Pointer to location to receive parent node + * \return 0 on success, 1 on failure + * + * If there is a parent node, but it is not an element node and element_only + * is true, then act as if no parent existed. + * + * Postcondition: if there is a parent, then result's reference count must be + * increased. */ typedef int (*hubbub_tree_get_parent)(void *ctx, void *node, bool element_only, void **result); /** - * Type of child presence query function + * Determine if a node has children + * + * \param ctx Client's context + * \param node The node to inspect + * \param result Location to receive result + * \return 0 on success, 1 on failure */ typedef int (*hubbub_tree_has_children)(void *ctx, void *node, bool *result); /** - * Type of form association function + * Associate a node with a form + * + * \param ctx Client's context + * \param form The form to associate with + * \param node The node to associate + * \return 0 on success, 1 on failure */ typedef int (*hubbub_tree_form_associate)(void *ctx, void *form, void *node); /** - * Type of attribute addition function + * Add attributes to a node + * + * \param ctx Client's context + * \param node The node to add to + * \param attributes Array of attributes to add + * \param n_attributes Number of entries in array + * \return 0 on success, 1 on failure */ typedef int (*hubbub_tree_add_attributes)(void *ctx, void *node, const hubbub_attribute *attributes, uint32_t n_attributes); /** - * Type of tree quirks mode notification function + * Notification of the quirks mode of a document + * + * \param ctx Client's context + * \param mode The quirks mode + * \return 0 on success, 1 on failure */ typedef int (*hubbub_tree_set_quirks_mode)(void *ctx, hubbub_quirks_mode mode); /** - * Type of encoding change notification function + * Notification that a potential encoding change is required + * + * \param ctx Client's context + * \param charset The new charset for the source data + * \return 0 to ignore the change and continue using the current input handler, + * 1 to stop processing immediately and return control to the client. */ typedef int (*hubbub_tree_encoding_change)(void *ctx, const char *encname); -- cgit v1.2.3