mirror of
https://github.com/rkd77/elinks.git
synced 2024-10-08 05:04:16 -04:00
DOM: Change code documentation to be Doxygen "compliant"
This commit is contained in:
Jonas Fonseca
parent
4d248638be
commit
93e9cf089e
@ -1,46 +1,78 @@
|
||||
#ifndef EL_DOM_CODE_H
|
||||
#define EL_DOM_CODE_H
|
||||
|
||||
/* API Doc :: dom-code */
|
||||
|
||||
/** DOM status/error/exception codes
|
||||
/** DOM status, error, and exception codes
|
||||
*
|
||||
* These enum values are used for return codes throughout the DOM engine.
|
||||
*/
|
||||
enum dom_code {
|
||||
/** ELinks specific codes: */
|
||||
DOM_CODE_OK = 0, /*: The sane default. */
|
||||
DOM_CODE_ERR = -1000, /*: Anything by DOM_CODE_OK. */
|
||||
/* ELinks specific codes: */
|
||||
DOM_CODE_OK = 0, /**< The sane default. */
|
||||
DOM_CODE_ERR = -1000, /**< Anything but #DOM_CODE_OK. */
|
||||
|
||||
DOM_CODE_INCOMPLETE, /*: The parsing could not be completed */
|
||||
DOM_CODE_FREE_NODE, /*: Discard the node */
|
||||
DOM_CODE_INCOMPLETE, /**< The parsing could not be completed */
|
||||
DOM_CODE_FREE_NODE, /**< Discard the node */
|
||||
|
||||
/** Error codes: */
|
||||
DOM_CODE_ALLOC_ERR, /*: Failed to allocate memory */
|
||||
DOM_CODE_MAX_DEPTH_ERR, /*: Stack max depth reached */
|
||||
DOM_CODE_VALUE_ERR, /*: Bad/unexpected value */
|
||||
DOM_CODE_ALLOC_ERR, /**< Failed to allocate memory */
|
||||
DOM_CODE_MAX_DEPTH_ERR, /**< Stack max depth reached */
|
||||
DOM_CODE_VALUE_ERR, /**< Bad/unexpected value */
|
||||
|
||||
/** DOM Level 1 codes: */
|
||||
/* DOM Level 1 codes: */
|
||||
|
||||
/** Index or size is negative, or greater than the allowed
|
||||
* value.*/
|
||||
DOM_CODE_INDEX_SIZE_ERR = 1,
|
||||
DOM_CODE_STRING_SIZE_ERR = 2,
|
||||
/** A specified range of text does not fit into a DOMString. */
|
||||
DOM_CODE_DOMSTRING_SIZE_ERR = 2,
|
||||
/** A node is inserted somewhere it doesn't belong. */
|
||||
DOM_CODE_HIERARCHY_REQUEST_ERR = 3,
|
||||
/** A node is used in a different document than the one that
|
||||
* created it (that doesn't support it). */
|
||||
DOM_CODE_WRONG_DOCUMENT_ERR = 4,
|
||||
/** An invalid or illegal character is specified, such as in an
|
||||
* XML name. */
|
||||
DOM_CODE_INVALID_CHARACTER_ERR = 5,
|
||||
/** Data is specified for a node which does not support data. */
|
||||
DOM_CODE_NO_DATA_ALLOWED_ERR = 6,
|
||||
/** An attempt is made to modify an object where modifications
|
||||
* are not allowed. */
|
||||
DOM_CODE_NO_MODIFICATION_ALLOWED_ERR = 7,
|
||||
/** An attempt is made to reference a node in a context where it
|
||||
* does not exist. */
|
||||
DOM_CODE_NOT_FOUND_ERR = 8,
|
||||
/** The implementation does not support the requested type of
|
||||
* object or operation. */
|
||||
DOM_CODE_NOT_SUPPORTED_ERR = 9,
|
||||
/** An attempt is made to add an attribute that is already in
|
||||
* use elsewhere. */
|
||||
DOM_CODE_INUSE_ATTRIBUTE_ERR = 10,
|
||||
|
||||
/** Introduced in DOM Level 2: */
|
||||
/* Introduced in DOM Level 2: */
|
||||
|
||||
/** An attempt is made to use an object that is not, or is no
|
||||
* longer, usable. */
|
||||
DOM_CODE_INVALID_STATE_ERR = 11,
|
||||
/** An invalid or illegal string is specified. */
|
||||
DOM_CODE_SYNTAX_ERR = 12,
|
||||
/** An attempt is made to modify the type of the underlying
|
||||
* object. */
|
||||
DOM_CODE_INVALID_MODIFICATION_ERR = 13,
|
||||
/** An attempt is made to create or change an object in a way
|
||||
* which is incorrect with regard to namespaces. */
|
||||
DOM_CODE_NAMESPACE_ERR = 14,
|
||||
/** A parameter or an operation is not supported by the
|
||||
* underlying object. */
|
||||
DOM_CODE_INVALID_ACCESS_ERR = 15,
|
||||
|
||||
/** Introduced in DOM Level 3: */
|
||||
/* Introduced in DOM Level 3: */
|
||||
|
||||
/** A call to a method such as insertBefore or removeChild would
|
||||
* make the Node invalid with respect to "partial validity",
|
||||
* this exception would beraised and the operation would not be
|
||||
* done. This code is used in DOM Level 3 Validation. */
|
||||
DOM_CODE_VALIDATION_ERR = 16,
|
||||
/** A type of an object is incompatible with the expected type
|
||||
* of the parameter associated to the object. */
|
||||
DOM_CODE_TYPE_MISMATCH_ERR = 17,
|
||||
};
|
||||
|
||||
|
||||
@ -4,8 +4,6 @@
|
||||
struct dom_node;
|
||||
struct dom_stack;
|
||||
|
||||
/* API Doc :: dom-config */
|
||||
|
||||
/** DOM Configuration
|
||||
*
|
||||
* The DOMConfiguration interface represents the configuration of a document.
|
||||
@ -13,10 +11,12 @@ struct dom_stack;
|
||||
* document normalization is done, such as replacing the CDATASection nodes
|
||||
* with Text nodes.
|
||||
*
|
||||
* Note: Parameters are similar to features and properties used in SAX2 [SAX].
|
||||
* Note: Parameters are similar to features and properties used in SAX2.
|
||||
*/
|
||||
|
||||
/** DOM configuration flags.
|
||||
*
|
||||
* The following list of parameters defined in the DOM: */
|
||||
|
||||
enum dom_config_flag {
|
||||
/** "cdata-sections"
|
||||
*
|
||||
@ -72,9 +72,9 @@ enum dom_config_flag {
|
||||
struct dom_error;
|
||||
|
||||
struct dom_config {
|
||||
enum dom_config_flag flags; /*: DOM configuration flags. */
|
||||
enum dom_config_flag flags; /**< DOM configuration flags. */
|
||||
|
||||
/** FIXME: "error-handler"
|
||||
/** A user defined error handler.
|
||||
*
|
||||
* Contains an error handler. If an error is encountered in the
|
||||
* document, this handler is called. When called, DOMError.relatedData
|
||||
|
||||
@ -4,8 +4,6 @@
|
||||
#include "dom/string.h"
|
||||
#include "util/error.h"
|
||||
|
||||
/* API Doc :: dom-scanner */
|
||||
|
||||
/* Define if you want a talking scanner */
|
||||
/* #define DEBUG_DOM_SCANNER */
|
||||
|
||||
@ -104,7 +102,7 @@ struct dom_scanner_info {
|
||||
|
||||
/** Initializes a DOM scanner
|
||||
*
|
||||
* See struct ref:[dom_scanner] for a description of the `int` flags. */
|
||||
* See struct #dom_scanner for a description of the `int` flags. */
|
||||
void init_dom_scanner(struct dom_scanner *scanner, struct dom_scanner_info *scanner_info,
|
||||
struct dom_string *string, int state, int count_lines, int complete,
|
||||
int check_complete, int detect_error);
|
||||
@ -125,21 +123,23 @@ struct dom_scanner {
|
||||
unsigned char *string;
|
||||
/** The end of the scanned string. */
|
||||
unsigned char *end;
|
||||
/**
|
||||
/** The current position in the sstring being scanned.
|
||||
*
|
||||
* The position in the string where to scan next and the end of the
|
||||
* string. If position is NULL it means that no more tokens can be
|
||||
* retrieved from the string. */
|
||||
unsigned char *position;
|
||||
|
||||
/**
|
||||
* The current token. If the number of scanned tokens is less than
|
||||
* ref:[DOM_SCANNER_TOKENS] it is because there are no more tokens in
|
||||
/** The current token.
|
||||
*
|
||||
* If the number of scanned tokens is less than
|
||||
* #DOM_SCANNER_TOKENS it is because there are no more tokens in
|
||||
* the string. */
|
||||
struct dom_scanner_token *current;
|
||||
/** The number of scanned tokens left in the table. */
|
||||
int tokens;
|
||||
|
||||
/** The 'meta' scanner information */
|
||||
/** The 'meta' scanner information. */
|
||||
struct dom_scanner_info *info;
|
||||
|
||||
#ifdef DEBUG_SCANNER
|
||||
@ -151,19 +151,20 @@ struct dom_scanner {
|
||||
/* The following two flags are used when parsing is incremental and
|
||||
* the scanner must ensure that only tokens that are complete are
|
||||
* generated. */
|
||||
unsigned int check_complete:1; /*: Only generate complete tokens */
|
||||
unsigned int incomplete:1; /*: The scanned string is incomplete */
|
||||
unsigned int check_complete:1; /**< Only generate complete tokens */
|
||||
unsigned int incomplete:1; /**< The scanned string is incomplete */
|
||||
|
||||
unsigned int detect_errors:1; /*: Check for markup errors */
|
||||
unsigned int found_error; /*: Did we already report this error? */
|
||||
unsigned int detect_errors:1; /**< Check for markup errors */
|
||||
unsigned int found_error; /**< Did we already report this error? */
|
||||
|
||||
unsigned int count_lines:1; /*: Is line counting enbaled? */
|
||||
unsigned int lineno; /*: Line # of the last scanned token */
|
||||
unsigned int count_lines:1; /**< Is line counting enbaled? */
|
||||
unsigned int lineno; /**< Line # of the last scanned token */
|
||||
|
||||
/** Some state indicator only meaningful to the scanner internals */
|
||||
int state;
|
||||
|
||||
/**
|
||||
/** Token table.
|
||||
*
|
||||
* The table contain already scanned tokens. It is maintained in
|
||||
* order to optimize the scanning a bit and make it possible to look
|
||||
* ahead at the next token. You should always use the accessors
|
||||
@ -223,7 +224,7 @@ skip_dom_scanner_tokens(struct dom_scanner *scanner, int skipto, int precedence)
|
||||
|
||||
/** Map a string to internal ID
|
||||
*
|
||||
* Looks up the string from @ident to @end to in the scanners string mapping
|
||||
* Looks up the string from ident to end to in the scanners string mapping
|
||||
* table. */
|
||||
int
|
||||
map_dom_scanner_string(struct dom_scanner *scanner,
|
||||
|
||||
@ -11,8 +11,6 @@ struct sgml_parser;
|
||||
struct string;
|
||||
struct uri;
|
||||
|
||||
/* API Doc :: dom-sgml-parser */
|
||||
|
||||
/** SGML parser type
|
||||
*
|
||||
* There are two kinds of parser types: One that optimises one-time access to
|
||||
@ -40,10 +38,10 @@ enum sgml_parser_type {
|
||||
* These flags control how the parser behaves.
|
||||
*/
|
||||
enum sgml_parser_flag {
|
||||
SGML_PARSER_COUNT_LINES = 1, /*: Make line numbers available. */
|
||||
SGML_PARSER_COMPLETE = 2, /*: Used internally when incremental. */
|
||||
SGML_PARSER_INCREMENTAL = 4, /*: Parse chunks of input. */
|
||||
SGML_PARSER_DETECT_ERRORS = 8, /*: Report errors. */
|
||||
SGML_PARSER_COUNT_LINES = 1, /**< Make line numbers available. */
|
||||
SGML_PARSER_COMPLETE = 2, /**< Used internally when incremental. */
|
||||
SGML_PARSER_INCREMENTAL = 4, /**< Parse chunks of input. */
|
||||
SGML_PARSER_DETECT_ERRORS = 8, /**< Report errors. */
|
||||
};
|
||||
|
||||
/** SGML parser state
|
||||
@ -66,7 +64,7 @@ struct sgml_parser_state {
|
||||
*
|
||||
* Called by the SGML parser when a parsing error has occurred.
|
||||
*
|
||||
* If the return code is not ref:[DOM_CODE_OK] the parsing will be
|
||||
* If the return code is not #DOM_CODE_OK the parsing will be
|
||||
* ended and that code will be returned. */
|
||||
typedef enum dom_code
|
||||
(*sgml_error_T)(struct sgml_parser *, struct dom_string *, unsigned int);
|
||||
@ -76,22 +74,23 @@ typedef enum dom_code
|
||||
*
|
||||
* This struct hold info used while parsing SGML data.
|
||||
*
|
||||
* NOTE: The only variable the user should set is ref:[sgml_parser.error_func].
|
||||
* @note The only variable the user should set is
|
||||
* sgml_parser.error_func.
|
||||
*/
|
||||
struct sgml_parser {
|
||||
enum sgml_parser_type type; /*: Stream or tree */
|
||||
enum sgml_parser_flag flags; /*: Flags that control the behaviour */
|
||||
enum sgml_parser_type type; /**< Stream or tree */
|
||||
enum sgml_parser_flag flags; /**< Flags that control the behaviour */
|
||||
|
||||
struct sgml_info *info; /*: Backend dependent info */
|
||||
struct sgml_info *info; /**< Backend dependent info */
|
||||
|
||||
struct dom_string uri; /*: The URI of the DOM document */
|
||||
struct dom_node *root; /*: The document root node */
|
||||
struct dom_string uri; /**< The URI of the DOM document */
|
||||
struct dom_node *root; /**< The document root node */
|
||||
|
||||
enum dom_code code; /*: The latest (error) code */
|
||||
sgml_error_T error_func; /*: Called for detected errors */
|
||||
enum dom_code code; /**< The latest (error) code */
|
||||
sgml_error_T error_func; /**< Called for detected errors */
|
||||
|
||||
struct dom_stack stack; /*: A stack for tracking parsed nodes */
|
||||
struct dom_stack parsing; /*: Used for tracking parsing states */
|
||||
struct dom_stack stack; /**< A stack for tracking parsed nodes */
|
||||
struct dom_stack parsing; /**< Used for tracking parsing states */
|
||||
};
|
||||
|
||||
|
||||
@ -99,12 +98,13 @@ struct sgml_parser {
|
||||
*
|
||||
* Initialise an SGML parser with the given properties.
|
||||
*
|
||||
* type:: Stream or tree; one-time or persistant.
|
||||
* doctype:: The document type, this affects what sub type nodes are given.
|
||||
* uri:: The URI of the document root.
|
||||
* flags:: Flags controlling the behaviour of the parser.
|
||||
* @param type Stream or tree; one-time or persistant.
|
||||
* @param doctype The document type, this affects what sub type nodes are
|
||||
* given.
|
||||
* @param uri The URI of the document root.
|
||||
* @param flags Flags controlling the behaviour of the parser.
|
||||
*
|
||||
* Returns the created parser or NULL.
|
||||
* @returns The created parser or NULL.
|
||||
*/
|
||||
struct sgml_parser *
|
||||
init_sgml_parser(enum sgml_parser_type type, enum sgml_document_type doctype,
|
||||
@ -112,34 +112,35 @@ init_sgml_parser(enum sgml_parser_type type, enum sgml_document_type doctype,
|
||||
|
||||
/** Release an SGML parser
|
||||
*
|
||||
* Deallocates all resources, _expect_ the root node.
|
||||
* Deallocates all resources, except the root node.
|
||||
*
|
||||
* parser:: The parser being released.
|
||||
* @param parser The parser being released.
|
||||
*/
|
||||
void done_sgml_parser(struct sgml_parser *parser);
|
||||
|
||||
/** Parse a chunk of SGML source
|
||||
*
|
||||
* Parses the given `buffer`. For incremental rendering the last buffer can be
|
||||
* Parses the given buffer. For incremental rendering the last buffer can be
|
||||
* signals through the `complete` parameter.
|
||||
*
|
||||
* parser:: A parser created with ref:[init_sgml_parser].
|
||||
* buf:: A buffer containing the chunk to parse.
|
||||
* bufsize:: The size of the buffer given in the buf parameter.
|
||||
* complete:: Whether this is the last chunk to parse.
|
||||
* @param parser A parser created with #init_sgml_parser.
|
||||
* @param buf A buffer containing the chunk to parse.
|
||||
* @param bufsize The size of the buffer given in the buf parameter.
|
||||
* @param complete Whether this is the last chunk to parse.
|
||||
*
|
||||
* The returned code is ref:[DOM_CODE_OK] if the buffer was
|
||||
* successfully parserd, else a code hinting at the error.
|
||||
* @returns #DOM_CODE_OK if the buffer was successfully parsed,
|
||||
* else a code hinting at the error.
|
||||
*/
|
||||
enum dom_code
|
||||
parse_sgml(struct sgml_parser *parser, unsigned char *buf, size_t bufsize, int complete);
|
||||
|
||||
/** Get the line position in the source
|
||||
*
|
||||
* Returns what line number the parser is currently at or zero if there has
|
||||
* been no parsing yet.
|
||||
* @note Line numbers are recorded in the scanner tokens.
|
||||
*
|
||||
* NOTE: Line numbers are recorded in the scanner tokens.
|
||||
* @param parser A parser created with #init_sgml_parser.
|
||||
* @returns What line number the parser is currently at or zero if
|
||||
* there has been no parsing yet.
|
||||
*/
|
||||
unsigned int get_sgml_parser_line_number(struct sgml_parser *parser);
|
||||
|
||||
|
||||
@ -8,8 +8,6 @@
|
||||
|
||||
struct dom_stack;
|
||||
|
||||
/* API Doc :: dom-stack */
|
||||
|
||||
/** DOM stack callback
|
||||
*
|
||||
* Used by contexts, for 'hooking' into the node traversing. */
|
||||
@ -28,7 +26,8 @@ struct dom_stack_state {
|
||||
* The depth of the state in the stack. This is amongst other things
|
||||
* used to get the state object data. */
|
||||
unsigned int depth;
|
||||
/** Whether this stack state can be popped with pop_dom_*() family. */
|
||||
/** Whether this stack state can be popped with #pop_dom_node,
|
||||
* #pop_dom_nodes, or #pop_dom_state. */
|
||||
unsigned int immutable:1;
|
||||
};
|
||||
|
||||
@ -38,9 +37,9 @@ struct dom_stack_state {
|
||||
* stack. */
|
||||
struct dom_stack_context_info {
|
||||
/**
|
||||
* This member tells whether the stack should allocate objects for each
|
||||
* state to be assigned to the state's @data member. Zero means no
|
||||
* state data should be allocated. */
|
||||
* The number of bytes to allocate on the stack for each state's
|
||||
* data member. Zero means no state data should be allocated.
|
||||
* */
|
||||
size_t object_size;
|
||||
|
||||
/** Callbacks to be called when pushing nodes. */
|
||||
@ -59,7 +58,7 @@ struct dom_stack_context {
|
||||
/**
|
||||
* This is one big array of context specific objects. For the SGML
|
||||
* parser this holds DTD-oriented info about the node (recorded in
|
||||
* struct sgml_node_info). E.g. whether an element node is optional.
|
||||
* struct #sgml_node_info). E.g. whether an element node is optional.
|
||||
*/
|
||||
unsigned char *state_objects;
|
||||
|
||||
@ -72,7 +71,7 @@ enum dom_stack_flag {
|
||||
/** No flag needed. */
|
||||
DOM_STACK_FLAG_NONE = 0,
|
||||
|
||||
/** Free nodes when popping by calling ref:[done_dom_node]. */
|
||||
/** Free nodes when popping by calling #done_dom_node. */
|
||||
DOM_STACK_FLAG_FREE_NODES = 1,
|
||||
};
|
||||
|
||||
@ -97,24 +96,24 @@ struct dom_stack {
|
||||
|
||||
/**
|
||||
* The current context. Only meaningful within
|
||||
* ref:[dom_stack_callback_T] functions. */
|
||||
* #dom_stack_callback_T functions. */
|
||||
struct dom_stack_context *current;
|
||||
};
|
||||
|
||||
/** Check whether stack is empty or not
|
||||
*
|
||||
* stack:: The stack to check.
|
||||
* @param stack The stack to check.
|
||||
*
|
||||
* Returns non-zero if stack is empty. */
|
||||
* @returns Non-zero if stack is empty. */
|
||||
#define dom_stack_is_empty(stack) \
|
||||
(!(stack)->states || (stack)->depth == 0)
|
||||
|
||||
/** Access state by offset from top
|
||||
*
|
||||
* stack:: The stack to fetch the state from.
|
||||
* top_offset:: The offset from the stack top, zero is the top.
|
||||
* @param stack The stack to fetch the state from.
|
||||
* @param top_offset The offset from the stack top, zero is the top.
|
||||
*
|
||||
* Returns the requested state. */
|
||||
* @returns The requested state. */
|
||||
static inline struct dom_stack_state *
|
||||
get_dom_stack_state(struct dom_stack *stack, int top_offset)
|
||||
{
|
||||
@ -125,9 +124,9 @@ get_dom_stack_state(struct dom_stack *stack, int top_offset)
|
||||
|
||||
/** Access the stack top
|
||||
*
|
||||
* stack:: The stack to get the top state from.
|
||||
* @param stack The stack to get the top state from.
|
||||
*
|
||||
* Returns the top state. */
|
||||
* @returns The top state. */
|
||||
#define get_dom_stack_top(stack) \
|
||||
get_dom_stack_state(stack, 0)
|
||||
|
||||
@ -136,11 +135,11 @@ get_dom_stack_state(struct dom_stack *stack, int top_offset)
|
||||
* Similar to ref:[get_dom_stack_state], this will fetch the data
|
||||
* associated with the state for the given context.
|
||||
*
|
||||
* context:: The context to get data from.
|
||||
* state:: The stack state to get data from.
|
||||
* @param context The context to get data from.
|
||||
* @param state The stack state to get data from.
|
||||
*
|
||||
* Returns the state data or NULL if ref:[dom_stack_context_info.object_size]
|
||||
* was zero. */
|
||||
* @returns The state data or NULL if
|
||||
* #dom_stack_context_info.object_size was zero. */
|
||||
static inline void *
|
||||
get_dom_stack_state_data(struct dom_stack_context *context,
|
||||
struct dom_stack_state *state)
|
||||
@ -156,8 +155,6 @@ get_dom_stack_state_data(struct dom_stack_context *context,
|
||||
|
||||
/*#define DOM_STACK_TRACE*/
|
||||
|
||||
#ifdef DOM_STACK_TRACE
|
||||
extern struct dom_stack_context_info dom_stack_trace_context_info;
|
||||
/** Get debug info from the DOM stack
|
||||
*
|
||||
* Define `DOM_STACK_TRACE` to have debug info about the nodes added printed to
|
||||
@ -165,11 +162,13 @@ extern struct dom_stack_context_info dom_stack_trace_context_info;
|
||||
*
|
||||
* Run as:
|
||||
*
|
||||
* ELINKS_LOG=/tmp/dom-dump.txt ./elinks -no-connect <url>
|
||||
* ELINKS_LOG=/tmp/dom-dump.txt ./elinks -no-connect URL
|
||||
*
|
||||
* to have the debug dumped into a file. */
|
||||
#ifdef DOM_STACK_TRACE
|
||||
#define add_dom_stack_tracer(stack, name) \
|
||||
add_dom_stack_context(stack, name, &dom_stack_trace_context_info)
|
||||
extern struct dom_stack_context_info dom_stack_trace_context_info;
|
||||
#else
|
||||
#define add_dom_stack_tracer(stack, name) /* Nada */
|
||||
#endif
|
||||
@ -192,15 +191,17 @@ extern struct dom_stack_context_info dom_stack_trace_context_info;
|
||||
/* Life cycle functions. */
|
||||
|
||||
/** Initialise a DOM stack
|
||||
* stack:: Pointer to a (preallocated) stack.
|
||||
* flags:: Any flags needed for controlling the behaviour of the stack.
|
||||
*
|
||||
* @param stack Pointer to a (preallocated) stack.
|
||||
* @param flags Any flags needed for controlling the behaviour of the stack.
|
||||
*/
|
||||
void init_dom_stack(struct dom_stack *stack, enum dom_stack_flag flags);
|
||||
|
||||
/** Release a DOM stack
|
||||
*
|
||||
* Free all resources collected by the stack.
|
||||
*
|
||||
* stack:: The stack to release. */
|
||||
* @param stack The stack to release. */
|
||||
void done_dom_stack(struct dom_stack *stack);
|
||||
|
||||
/** Add a context to the stack
|
||||
@ -209,16 +210,17 @@ void done_dom_stack(struct dom_stack *stack);
|
||||
* created states and/or if you want to install callbacks for pushing or
|
||||
* popping.
|
||||
*
|
||||
* stack:: The stack where the context should be created.
|
||||
* data:: Private data to be stored in ref:[dom_stack_context.data].
|
||||
* context_info:: Information about state objects and node callbacks.
|
||||
* @param stack The stack where the context should be created.
|
||||
* @param data Private data to be stored in ref:[dom_stack_context.data].
|
||||
* @param context_info Information about state objects and node callbacks.
|
||||
*
|
||||
* Returns a pointer to the newly created context or NULL. */
|
||||
* @returns A pointer to the newly created context or NULL. */
|
||||
struct dom_stack_context *
|
||||
add_dom_stack_context(struct dom_stack *stack, void *data,
|
||||
struct dom_stack_context_info *context_info);
|
||||
|
||||
/** Unregister a stack context
|
||||
*
|
||||
* This should be done especially for temporary stack contexts (without any
|
||||
* callbacks) so that they do not increasing the memory usage. */
|
||||
void done_dom_stack_context(struct dom_stack *stack, struct dom_stack_context *context);
|
||||
@ -227,16 +229,17 @@ void done_dom_stack_context(struct dom_stack *stack, struct dom_stack_context *c
|
||||
*
|
||||
* Makes the pushed node the new top of the stack.
|
||||
*
|
||||
* stack:: The stack to push onto.
|
||||
* node:: The node to push onto the stack.
|
||||
* @param stack The stack to push onto.
|
||||
* @param node The node to push onto the stack.
|
||||
*
|
||||
* If an error occurs the node is released with ref:[done_dom_node] and NULL is
|
||||
* returned. Else the pushed node is returned. */
|
||||
* @returns If an error occurs the node is released with
|
||||
* #done_dom_node and NULL is returned. Else the pushed
|
||||
* node is returned. */
|
||||
enum dom_code push_dom_node(struct dom_stack *stack, struct dom_node *node);
|
||||
|
||||
/** Pop the top stack state
|
||||
*
|
||||
* stack:: The stack to pop from. */
|
||||
* @param stack The stack to pop from. */
|
||||
void pop_dom_node(struct dom_stack *stack);
|
||||
|
||||
/** Conditionally pop the stack states
|
||||
@ -244,7 +247,8 @@ void pop_dom_node(struct dom_stack *stack);
|
||||
* Searches the stack (using ref:[search_dom_stack]) for a specific node and
|
||||
* pops all states until that particular state is met.
|
||||
*
|
||||
* NOTE: The popping is stopped if an immutable state is encountered. */
|
||||
* @note The popping is stopped if an immutable state is
|
||||
* encountered. */
|
||||
void pop_dom_nodes(struct dom_stack *stack, enum dom_node_type type,
|
||||
struct dom_string *string);
|
||||
|
||||
@ -253,8 +257,8 @@ void pop_dom_nodes(struct dom_stack *stack, enum dom_node_type type,
|
||||
* Pop all stack states until a specific state is reached. The target state
|
||||
* is also popped.
|
||||
*
|
||||
* stack:: The stack to pop from.
|
||||
* target:: The state to pop until and including. */
|
||||
* @param stack The stack to pop from.
|
||||
* @param target The state to pop until and including. */
|
||||
void pop_dom_state(struct dom_stack *stack, struct dom_stack_state *target);
|
||||
|
||||
/** Search the stack states
|
||||
@ -262,11 +266,11 @@ void pop_dom_state(struct dom_stack *stack, struct dom_stack_state *target);
|
||||
* The string comparison is done against the ref:[dom_node.string] member of
|
||||
* the of the state nodes.
|
||||
*
|
||||
* stack:: The stack to search in.
|
||||
* type:: The type of node to match against.
|
||||
* string:: The string to match against.
|
||||
* @param stack The stack to search in.
|
||||
* @param type The type of node to match against.
|
||||
* @param string The string to match against.
|
||||
*
|
||||
* Returns a state that matched the type and string or NULL. */
|
||||
* @returns A state that matched the type and string or NULL. */
|
||||
struct dom_stack_state *
|
||||
search_dom_stack(struct dom_stack *stack, enum dom_node_type type,
|
||||
struct dom_string *string);
|
||||
@ -275,12 +279,12 @@ search_dom_stack(struct dom_stack *stack, enum dom_node_type type,
|
||||
*
|
||||
* Visits each node in the DOM tree rooted at a given node, pre-order style.
|
||||
*
|
||||
* stack:: The stack to use for walking the nodes.
|
||||
* root:: The root node to start from.
|
||||
* @param stack The stack to use for walking the nodes.
|
||||
* @param root The root node to start from.
|
||||
*
|
||||
* It is assummed that the given stack has been initialised with
|
||||
* ref:[init_dom_stack] and that the caller already added one or more
|
||||
* context to the stack. */
|
||||
* #init_dom_stack and that the caller already added one or more context
|
||||
* to the stack. */
|
||||
void walk_dom_nodes(struct dom_stack *stack, struct dom_node *root);
|
||||
|
||||
#endif
|
||||
|
||||
Loading…
Reference in New Issue
Block a user