aniani/elinks
1
0
Fork 0
mirror of https://github.com/rkd77/elinks.git synced 2025-02-02 15:09:23 -05:00
Code

DOM: Change code documentation to be Doxygen "compliant"

Browse Source
This commit is contained in:
Jonas Fonseca 2006-12-10 01:17:35 +01:00
parent 4d248638be
commit 93e9cf089e
5 changed files with 156 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
src/dom/code.h
View File

@ -1,46 +1,78 @@
#ifndef EL_DOM_CODE_H #ifndef EL_DOM_CODE_H
#define EL_DOM_CODE_H #define EL_DOM_CODE_H
/* API Doc :: dom-code */ /** DOM status, error, and exception codes
/** DOM status/error/exception codes
* *
* These enum values are used for return codes throughout the DOM engine. * These enum values are used for return codes throughout the DOM engine.
*/ */
enum dom_code { enum dom_code {
/** ELinks specific codes: */ /* ELinks specific codes: */
DOM_CODE_OK = 0, /*: The sane default. */ DOM_CODE_OK = 0, /**< The sane default. */
DOM_CODE_ERR = -1000, /*: Anything by DOM_CODE_OK. */ DOM_CODE_ERR = -1000, /**< Anything but #DOM_CODE_OK. */
DOM_CODE_INCOMPLETE, /*: The parsing could not be completed */ DOM_CODE_INCOMPLETE, /**< The parsing could not be completed */
DOM_CODE_FREE_NODE, /*: Discard the node */ DOM_CODE_FREE_NODE, /**< Discard the node */
/** Error codes: */ DOM_CODE_ALLOC_ERR, /**< Failed to allocate memory */
DOM_CODE_ALLOC_ERR, /*: Failed to allocate memory */ DOM_CODE_MAX_DEPTH_ERR, /**< Stack max depth reached */
DOM_CODE_MAX_DEPTH_ERR, /*: Stack max depth reached */ DOM_CODE_VALUE_ERR, /**< Bad/unexpected value */
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_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, 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, 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, DOM_CODE_INVALID_CHARACTER_ERR = 5,
/** Data is specified for a node which does not support data. */
DOM_CODE_NO_DATA_ALLOWED_ERR = 6, 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, 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, DOM_CODE_NOT_FOUND_ERR = 8,
/** The implementation does not support the requested type of
* object or operation. */
DOM_CODE_NOT_SUPPORTED_ERR = 9, 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, 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, DOM_CODE_INVALID_STATE_ERR = 11,
/** An invalid or illegal string is specified. */
DOM_CODE_SYNTAX_ERR = 12, DOM_CODE_SYNTAX_ERR = 12,
/** An attempt is made to modify the type of the underlying
* object. */
DOM_CODE_INVALID_MODIFICATION_ERR = 13, 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, DOM_CODE_NAMESPACE_ERR = 14,
/** A parameter or an operation is not supported by the
* underlying object. */
DOM_CODE_INVALID_ACCESS_ERR = 15, 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, 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, DOM_CODE_TYPE_MISMATCH_ERR = 17,
}; };

12
src/dom/configuration.h
View File

@ -4,8 +4,6 @@
struct dom_node; struct dom_node;
struct dom_stack; struct dom_stack;
/* API Doc :: dom-config */
/** DOM Configuration /** DOM Configuration
* *
* The DOMConfiguration interface represents the configuration of a document. * 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 * document normalization is done, such as replacing the CDATASection nodes
* with Text 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: */ * The following list of parameters defined in the DOM: */
enum dom_config_flag { enum dom_config_flag {
/** "cdata-sections" /** "cdata-sections"
* *
@ -72,9 +72,9 @@ enum dom_config_flag {
struct dom_error; struct dom_error;
struct dom_config { 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 * Contains an error handler. If an error is encountered in the
* document, this handler is called. When called, DOMError.relatedData * document, this handler is called. When called, DOMError.relatedData

33
src/dom/scanner.h
View File

@ -4,8 +4,6 @@
#include "dom/string.h" #include "dom/string.h"
#include "util/error.h" #include "util/error.h"
/* API Doc :: dom-scanner */
/* Define if you want a talking scanner */ /* Define if you want a talking scanner */
/* #define DEBUG_DOM_SCANNER */ /* #define DEBUG_DOM_SCANNER */
@ -104,7 +102,7 @@ struct dom_scanner_info {
/** Initializes a DOM scanner /** 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, 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, struct dom_string *string, int state, int count_lines, int complete,
int check_complete, int detect_error); int check_complete, int detect_error);
@ -125,21 +123,23 @@ struct dom_scanner {
unsigned char *string; unsigned char *string;
/** The end of the scanned string. */ /** The end of the scanned string. */
unsigned char *end; 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 * 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 * string. If position is NULL it means that no more tokens can be
* retrieved from the string. */ * retrieved from the string. */
unsigned char *position; unsigned char *position;
/** /** The current token.
* 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 * If the number of scanned tokens is less than
* #DOM_SCANNER_TOKENS it is because there are no more tokens in
* the string. */ * the string. */
struct dom_scanner_token *current; struct dom_scanner_token *current;
/** The number of scanned tokens left in the table. */ /** The number of scanned tokens left in the table. */
int tokens; int tokens;
/** The 'meta' scanner information */ /** The 'meta' scanner information. */
struct dom_scanner_info *info; struct dom_scanner_info *info;
#ifdef DEBUG_SCANNER #ifdef DEBUG_SCANNER
@ -151,19 +151,20 @@ struct dom_scanner {
/* The following two flags are used when parsing is incremental and /* The following two flags are used when parsing is incremental and
* the scanner must ensure that only tokens that are complete are * the scanner must ensure that only tokens that are complete are
* generated. */ * generated. */
unsigned int check_complete:1; /*: Only generate complete tokens */ unsigned int check_complete:1; /**< Only generate complete tokens */
unsigned int incomplete:1; /*: The scanned string is incomplete */ unsigned int incomplete:1; /**< The scanned string is incomplete */
unsigned int detect_errors:1; /*: Check for markup errors */ unsigned int detect_errors:1; /**< Check for markup errors */
unsigned int found_error; /*: Did we already report this error? */ unsigned int found_error; /**< Did we already report this error? */
unsigned int count_lines:1; /*: Is line counting enbaled? */ unsigned int count_lines:1; /**< Is line counting enbaled? */
unsigned int lineno; /*: Line # of the last scanned token */ unsigned int lineno; /**< Line # of the last scanned token */
/** Some state indicator only meaningful to the scanner internals */ /** Some state indicator only meaningful to the scanner internals */
int state; int state;
/** /** Token table.
*
* The table contain already scanned tokens. It is maintained in * The table contain already scanned tokens. It is maintained in
* order to optimize the scanning a bit and make it possible to look * order to optimize the scanning a bit and make it possible to look
* ahead at the next token. You should always use the accessors * 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 /** 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. */ * table. */
int int
map_dom_scanner_string(struct dom_scanner *scanner, map_dom_scanner_string(struct dom_scanner *scanner,

69
src/dom/sgml/parser.h
View File

@ -11,8 +11,6 @@ struct sgml_parser;
struct string; struct string;
struct uri; struct uri;
/* API Doc :: dom-sgml-parser */
/** SGML parser type /** SGML parser type
* *
* There are two kinds of parser types: One that optimises one-time access to * 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. * These flags control how the parser behaves.
*/ */
enum sgml_parser_flag { enum sgml_parser_flag {
SGML_PARSER_COUNT_LINES = 1, /*: Make line numbers available. */ SGML_PARSER_COUNT_LINES = 1, /**< Make line numbers available. */
SGML_PARSER_COMPLETE = 2, /*: Used internally when incremental. */ SGML_PARSER_COMPLETE = 2, /**< Used internally when incremental. */
SGML_PARSER_INCREMENTAL = 4, /*: Parse chunks of input. */ SGML_PARSER_INCREMENTAL = 4, /**< Parse chunks of input. */
SGML_PARSER_DETECT_ERRORS = 8, /*: Report errors. */ SGML_PARSER_DETECT_ERRORS = 8, /**< Report errors. */
}; };
/** SGML parser state /** SGML parser state
@ -66,7 +64,7 @@ struct sgml_parser_state {
* *
* Called by the SGML parser when a parsing error has occurred. * 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. */ * ended and that code will be returned. */
typedef enum dom_code typedef enum dom_code
(*sgml_error_T)(struct sgml_parser *, struct dom_string *, unsigned int); (*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. * 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 { struct sgml_parser {
enum sgml_parser_type type; /*: Stream or tree */ enum sgml_parser_type type; /**< Stream or tree */
enum sgml_parser_flag flags; /*: Flags that control the behaviour */ 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_string uri; /**< The URI of the DOM document */
struct dom_node *root; /*: The document root node */ struct dom_node *root; /**< The document root node */
enum dom_code code; /*: The latest (error) code */ enum dom_code code; /**< The latest (error) code */
sgml_error_T error_func; /*: Called for detected errors */ sgml_error_T error_func; /**< Called for detected errors */
struct dom_stack stack; /*: A stack for tracking parsed nodes */ struct dom_stack stack; /**< A stack for tracking parsed nodes */
struct dom_stack parsing; /*: Used for tracking parsing states */ struct dom_stack parsing; /**< Used for tracking parsing states */
}; };
@ -99,12 +98,13 @@ struct sgml_parser {
* *
* Initialise an SGML parser with the given properties. * Initialise an SGML parser with the given properties.
* *
* type:: Stream or tree; one-time or persistant. * @param type Stream or tree; one-time or persistant.
* doctype:: The document type, this affects what sub type nodes are given. * @param doctype The document type, this affects what sub type nodes are
* uri:: The URI of the document root. * given.
* flags:: Flags controlling the behaviour of the parser. * @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 * struct sgml_parser *
init_sgml_parser(enum sgml_parser_type type, enum sgml_document_type doctype, 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 /** 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); void done_sgml_parser(struct sgml_parser *parser);
/** Parse a chunk of SGML source /** 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. * signals through the `complete` parameter.
* *
* parser:: A parser created with ref:[init_sgml_parser]. * @param parser A parser created with #init_sgml_parser.
* buf:: A buffer containing the chunk to parse. * @param buf A buffer containing the chunk to parse.
* bufsize:: The size of the buffer given in the buf parameter. * @param bufsize The size of the buffer given in the buf parameter.
* complete:: Whether this is the last chunk to parse. * @param complete Whether this is the last chunk to parse.
* *
* The returned code is ref:[DOM_CODE_OK] if the buffer was * @returns #DOM_CODE_OK if the buffer was successfully parsed,
* successfully parserd, else a code hinting at the error. * else a code hinting at the error.
*/ */
enum dom_code enum dom_code
parse_sgml(struct sgml_parser *parser, unsigned char *buf, size_t bufsize, int complete); parse_sgml(struct sgml_parser *parser, unsigned char *buf, size_t bufsize, int complete);
/** Get the line position in the source /** Get the line position in the source
* *
* Returns what line number the parser is currently at or zero if there has * @note Line numbers are recorded in the scanner tokens.
* been no parsing yet.
* *
* 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); unsigned int get_sgml_parser_line_number(struct sgml_parser *parser);

96
src/dom/stack.h
View File

@ -8,8 +8,6 @@
struct dom_stack; struct dom_stack;
/* API Doc :: dom-stack */
/** DOM stack callback /** DOM stack callback
* *
* Used by contexts, for 'hooking' into the node traversing. */ * 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 * The depth of the state in the stack. This is amongst other things
* used to get the state object data. */ * used to get the state object data. */
unsigned int depth; 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; unsigned int immutable:1;
}; };
@ -38,9 +37,9 @@ struct dom_stack_state {
* stack. */ * stack. */
struct dom_stack_context_info { struct dom_stack_context_info {
/** /**
* This member tells whether the stack should allocate objects for each * The number of bytes to allocate on the stack for each state's
* state to be assigned to the state's @data member. Zero means no * data member. Zero means no state data should be allocated.
* state data should be allocated. */ * */
size_t object_size; size_t object_size;
/** Callbacks to be called when pushing nodes. */ /** 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 * This is one big array of context specific objects. For the SGML
* parser this holds DTD-oriented info about the node (recorded in * 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; unsigned char *state_objects;
@ -72,7 +71,7 @@ enum dom_stack_flag {
/** No flag needed. */ /** No flag needed. */
DOM_STACK_FLAG_NONE = 0, 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, DOM_STACK_FLAG_FREE_NODES = 1,
}; };
@ -97,24 +96,24 @@ struct dom_stack {
/** /**
* The current context. Only meaningful within * The current context. Only meaningful within
* ref:[dom_stack_callback_T] functions. */ * #dom_stack_callback_T functions. */
struct dom_stack_context *current; struct dom_stack_context *current;
}; };
/** Check whether stack is empty or not /** 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) \ #define dom_stack_is_empty(stack) \
(!(stack)->states || (stack)->depth == 0) (!(stack)->states || (stack)->depth == 0)
/** Access state by offset from top /** Access state by offset from top
* *
* stack:: The stack to fetch the state from. * @param stack The stack to fetch the state from.
* top_offset:: The offset from the stack top, zero is the top. * @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 * static inline struct dom_stack_state *
get_dom_stack_state(struct dom_stack *stack, int top_offset) 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 /** 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) \ #define get_dom_stack_top(stack) \
get_dom_stack_state(stack, 0) 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 * Similar to ref:[get_dom_stack_state], this will fetch the data
* associated with the state for the given context. * associated with the state for the given context.
* *
* context:: The context to get data from. * @param context The context to get data from.
* state:: The stack state 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] * @returns The state data or NULL if
* was zero. */ * #dom_stack_context_info.object_size was zero. */
static inline void * static inline void *
get_dom_stack_state_data(struct dom_stack_context *context, get_dom_stack_state_data(struct dom_stack_context *context,
struct dom_stack_state *state) struct dom_stack_state *state)
@ -156,8 +155,6 @@ get_dom_stack_state_data(struct dom_stack_context *context,
/*#define DOM_STACK_TRACE*/ /*#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 /** Get debug info from the DOM stack
* *
* Define `DOM_STACK_TRACE` to have debug info about the nodes added printed to * 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: * 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. */ * to have the debug dumped into a file. */
#ifdef DOM_STACK_TRACE
#define add_dom_stack_tracer(stack, name) \ #define add_dom_stack_tracer(stack, name) \
add_dom_stack_context(stack, name, &dom_stack_trace_context_info) add_dom_stack_context(stack, name, &dom_stack_trace_context_info)
extern struct dom_stack_context_info dom_stack_trace_context_info;
#else #else
#define add_dom_stack_tracer(stack, name) /* Nada */ #define add_dom_stack_tracer(stack, name) /* Nada */
#endif #endif
@ -192,15 +191,17 @@ extern struct dom_stack_context_info dom_stack_trace_context_info;
/* Life cycle functions. */ /* Life cycle functions. */
/** Initialise a DOM stack /** 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); void init_dom_stack(struct dom_stack *stack, enum dom_stack_flag flags);
/** Release a DOM stack /** Release a DOM stack
* *
* Free all resources collected by the 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); void done_dom_stack(struct dom_stack *stack);
/** Add a context to the 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 * created states and/or if you want to install callbacks for pushing or
* popping. * popping.
* *
* stack:: The stack where the context should be created. * @param stack The stack where the context should be created.
* data:: Private data to be stored in ref:[dom_stack_context.data]. * @param data Private data to be stored in ref:[dom_stack_context.data].
* context_info:: Information about state objects and node callbacks. * @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 * struct dom_stack_context *
add_dom_stack_context(struct dom_stack *stack, void *data, add_dom_stack_context(struct dom_stack *stack, void *data,
struct dom_stack_context_info *context_info); struct dom_stack_context_info *context_info);
/** Unregister a stack context /** Unregister a stack context
*
* This should be done especially for temporary stack contexts (without any * This should be done especially for temporary stack contexts (without any
* callbacks) so that they do not increasing the memory usage. */ * callbacks) so that they do not increasing the memory usage. */
void done_dom_stack_context(struct dom_stack *stack, struct dom_stack_context *context); 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. * Makes the pushed node the new top of the stack.
* *
* stack:: The stack to push onto. * @param stack The stack to push onto.
* node:: The node to push onto the stack. * @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 * @returns If an error occurs the node is released with
* returned. Else the pushed node is returned. */ * #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); enum dom_code push_dom_node(struct dom_stack *stack, struct dom_node *node);
/** Pop the top stack state /** 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); void pop_dom_node(struct dom_stack *stack);
/** Conditionally pop the stack states /** 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 * Searches the stack (using ref:[search_dom_stack]) for a specific node and
* pops all states until that particular state is met. * 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, void pop_dom_nodes(struct dom_stack *stack, enum dom_node_type type,
struct dom_string *string); 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 * Pop all stack states until a specific state is reached. The target state
* is also popped. * is also popped.
* *
* stack:: The stack to pop from. * @param stack The stack to pop from.
* target:: The state to pop until and including. */ * @param target The state to pop until and including. */
void pop_dom_state(struct dom_stack *stack, struct dom_stack_state *target); void pop_dom_state(struct dom_stack *stack, struct dom_stack_state *target);
/** Search the stack states /** 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 string comparison is done against the ref:[dom_node.string] member of
* the of the state nodes. * the of the state nodes.
* *
* stack:: The stack to search in. * @param stack The stack to search in.
* type:: The type of node to match against. * @param type The type of node to match against.
* string:: The string 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 * struct dom_stack_state *
search_dom_stack(struct dom_stack *stack, enum dom_node_type type, search_dom_stack(struct dom_stack *stack, enum dom_node_type type,
struct dom_string *string); 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. * Visits each node in the DOM tree rooted at a given node, pre-order style.
* *
* stack:: The stack to use for walking the nodes. * @param stack The stack to use for walking the nodes.
* root:: The root node to start from. * @param root The root node to start from.
* *
* It is assummed that the given stack has been initialised with * It is assummed that the given stack has been initialised with
* ref:[init_dom_stack] and that the caller already added one or more * #init_dom_stack and that the caller already added one or more context
* context to the stack. */ * to the stack. */
void walk_dom_nodes(struct dom_stack *stack, struct dom_node *root); void walk_dom_nodes(struct dom_stack *stack, struct dom_node *root);
#endif #endif