From 5d07c293d6fa169d665dc4e1ea3cea4271d92ccc Mon Sep 17 00:00:00 2001 From: John MacFarlane Date: Sat, 13 Dec 2014 22:11:02 -0800 Subject: Added API documentation to src/cmark.h. Closes #224. --- src/cmark.h | 155 ++++++++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 109 insertions(+), 46 deletions(-) (limited to 'src/cmark.h') diff --git a/src/cmark.h b/src/cmark.h index 85dffa4..9de1037 100644 --- a/src/cmark.h +++ b/src/cmark.h @@ -91,12 +91,14 @@ typedef enum { * ## Creating and Destroying Nodes */ -/** +/** Creates a new node of type 'type'. Note that the node may have + * other required properties, which it is the caller's responsibility + * to assign. */ CMARK_EXPORT cmark_node* cmark_node_new(cmark_node_type type); -/** +/** Frees the memory allocated for a node. */ CMARK_EXPORT void cmark_node_free(cmark_node *node); @@ -105,52 +107,83 @@ cmark_node_free(cmark_node *node); * ## Tree Traversal */ +/** Returns the next node in the sequence after 'node', or NULL if + * there is none. + */ CMARK_EXPORT cmark_node* cmark_node_next(cmark_node *node); -/** +/** Returns the previous node in the sequence after 'node', or NULL if + * there is none. */ CMARK_EXPORT cmark_node* cmark_node_previous(cmark_node *node); -/** +/** Returns the parent of 'node', or NULL if there is none. */ CMARK_EXPORT cmark_node* cmark_node_parent(cmark_node *node); -/** +/** Returns the first child of 'node', or NULL if 'node' has no children. */ CMARK_EXPORT cmark_node* cmark_node_first_child(cmark_node *node); -/** +/** Returns the last child of 'node', or NULL if 'node' has no children. */ CMARK_EXPORT cmark_node* cmark_node_last_child(cmark_node *node); /** * ## Iterator + * + * An iterator will walk through a tree of nodes, starting from a root + * node, returning one node at a time, together with information about + * whether the node is being entered or exited. The iterator will + * first descend to a child node, if there is one. When there is no + * child, the iterator will go to the next sibling. When there is no + * next sibling, the iterator will return to the parent (but with + * a 'cmark_event_type' of `CMARK_EVENT_EXIT`). The iterator will + * return `CMARK_EVENT_DONE` when it reaches the root node again. + * One natural application is an HTML renderer, where an `ENTER` event + * outputs an open tag and an `EXIT` event outputs a close tag. + * An iterator might also be used to transform an AST in some systematic + * way, for example, turning all level-3 headers into regular paragraphs. + * + * void + * usage_example(cmark_node *root) { + * cmark_event_type ev_type; + * cmark_iter *iter = cmark_iter_new(root); + * + * while ((ev_type = cmark_iter_next(iter)) != CMARK_EVENT_DONE) { + * cmark_node *cur = cmark_iter_get_node(iter); + * // Do something with `cur` and `ev_type` + * } + * + * cmark_iter_free(iter); + * } */ -/** +/** Creates a new iterator starting at 'root'. */ CMARK_EXPORT cmark_iter* cmark_iter_new(cmark_node *root); -/** +/** Frees the memory allocated for an iterator. */ CMARK_EXPORT void cmark_iter_free(cmark_iter *iter); -/** +/** Returns the event type (`CMARK_EVENT_ENTER`, `CMARK_EVENT_EXIT`, + * or `CMARK_EVENT_DONE`) for the next node. */ CMARK_EXPORT cmark_event_type cmark_iter_next(cmark_iter *iter); -/** +/** Returns the next node in the sequence described above. */ CMARK_EXPORT cmark_node* @@ -160,102 +193,108 @@ cmark_iter_get_node(cmark_iter *iter); * ## Accessors */ -/** +/** Returns the type of 'node', or `CMARK_NODE_NONE` on error. */ CMARK_EXPORT cmark_node_type cmark_node_get_type(cmark_node *node); -/** +/** Returns the string contents of 'node', or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_string_content(cmark_node *node); -/** +/** Sets the string contents of 'node'. Returns 1 on success, + * 0 on failure. */ CMARK_EXPORT int cmark_node_set_string_content(cmark_node *node, const char *content); -/** +/** Returns the header level of 'node', or 0 if 'node' is not a header. */ CMARK_EXPORT int cmark_node_get_header_level(cmark_node *node); -/** +/** Sets the header level of 'node', returning 1 on success and 0 on error. */ CMARK_EXPORT int cmark_node_set_header_level(cmark_node *node, int level); -/** +/** Returns the list type of 'node', or `CMARK_NO_LIST` if 'node' + * is not a list. */ CMARK_EXPORT cmark_list_type cmark_node_get_list_type(cmark_node *node); -/** +/** Sets the list type of 'node', returning 1 on success and 0 on error. */ CMARK_EXPORT int cmark_node_set_list_type(cmark_node *node, cmark_list_type type); -/** +/** Returns starting number of 'node', if it is an ordered list, otherwise 0. */ CMARK_EXPORT int cmark_node_get_list_start(cmark_node *node); -/** +/** Sets starting number of 'node', if it is an ordered list. Returns 1 + * on success, 0 on failure. */ CMARK_EXPORT int cmark_node_set_list_start(cmark_node *node, int start); -/** +/** Returns 1 if 'node' is a tight list, 0 otherwise. */ CMARK_EXPORT int cmark_node_get_list_tight(cmark_node *node); -/** +/** Sets the "tightness" of a list. Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_set_list_tight(cmark_node *node, int tight); -/** +/** Returns the info string from a fenced code block, or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_fence_info(cmark_node *node); -/** +/** Sets the info string in a fenced code block, returning 1 on + * success and 0 on failure. */ CMARK_EXPORT int cmark_node_set_fence_info(cmark_node *node, const char *info); -/** +/** Gets the URL of a link or image 'node', or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_url(cmark_node *node); -/** +/** Sets the URL of a link or image 'node'. Returns 1 on success, + * 0 on failure. */ CMARK_EXPORT int cmark_node_set_url(cmark_node *node, const char *url); -/** +/** Gets the title of a link or image 'node', or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_title(cmark_node *node); -/** +/** Sets the title of a link or image 'node'. Returns 1 on success, + * 0 on failure. */ CMARK_EXPORT int cmark_node_set_title(cmark_node *node, const char *title); -/** +/** Returns the line on which 'node' begins. */ CMARK_EXPORT int cmark_node_get_start_line(cmark_node *node); -/** +/** Returns the column at which 'node' begins. */ CMARK_EXPORT int cmark_node_get_start_column(cmark_node *node); -/** +/** Returns the line on which 'node' ends. */ CMARK_EXPORT int cmark_node_get_end_line(cmark_node *node); @@ -264,61 +303,83 @@ cmark_node_get_end_line(cmark_node *node); * ## Tree Manipulation */ -/** +/** Unlinks a 'node', removing it from the tree, but not freeing its + * memory. (Use 'cmark_node_free' for that.) */ CMARK_EXPORT void cmark_node_unlink(cmark_node *node); -/** +/** Inserts 'sibling' before 'node'. Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_insert_before(cmark_node *node, cmark_node *sibling); -/** +/** Inserts 'sibling' after 'node'. Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_insert_after(cmark_node *node, cmark_node *sibling); -/** +/** Adds 'child' to the beginning of the children of 'node'. + * Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_prepend_child(cmark_node *node, cmark_node *child); -/** +/** Adds 'child' to the end of the children of 'node'. + * Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_append_child(cmark_node *node, cmark_node *child); /** * ## Parsing + * + * Simple interface: + * + * cmark_node *document = cmark_parse_document("Hello *world*", 12); + * + * Streaming interface: + * + * cmark_parser *parser = cmark_parser_new(); + * FILE *fp = fopen("myfile.md", "r"); + * while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) { + * cmark_parser_feed(parser, buffer, bytes); + * if (bytes < sizeof(buffer)) { + * break; + * } + * } + * document = cmark_parser_finish(parser); + * cmark_parser_free(parser); */ -/** +/** Creates a new parser object. */ CMARK_EXPORT cmark_parser *cmark_parser_new(); -/** +/** Frees memory allocated for a parser object. */ CMARK_EXPORT void cmark_parser_free(cmark_parser *parser); -/** +/** Feeds a string of length 'len' to 'parser'. */ CMARK_EXPORT -cmark_node *cmark_parser_finish(cmark_parser *parser); +void cmark_parser_feed(cmark_parser *parser, const char *buffer, size_t len); -/** +/** Finish parsing and return a pointer to a tree of nodes. */ CMARK_EXPORT -void cmark_parser_feed(cmark_parser *parser, const char *buffer, size_t len); +cmark_node *cmark_parser_finish(cmark_parser *parser); -/** +/** Parse a CommonMark document in 'buffer' of length 'len'. + * Returns a pointer to a tree of nodes. */ CMARK_EXPORT cmark_node *cmark_parse_document(const char *buffer, size_t len); -/** +/** Parse a CommonMark document in file 'f', returning a pointer to + * a tree of nodes. */ CMARK_EXPORT cmark_node *cmark_parse_file(FILE *f); @@ -327,17 +388,19 @@ cmark_node *cmark_parse_file(FILE *f); * ## Rendering */ -/** +/** Render a 'node' tree for debugging purposes, showing + * the hierachy of nodes and their types and contents. */ CMARK_EXPORT char *cmark_render_ast(cmark_node *root); -/** +/** Render a 'node' tree as an HTML fragment. It is up to the user + * to add an appropriate header and footer. */ CMARK_EXPORT char *cmark_render_html(cmark_node *root); -/** +/** Render a 'node' tree as a groff man page, without the header. */ CMARK_EXPORT char *cmark_render_man(cmark_node *root); -- cgit v1.2.3