1
0
mirror of https://github.com/rkd77/elinks.git synced 2024-12-04 14:46:47 -05:00

DOM: Change code documentation to be Doxygen "compliant"

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

View File

@ -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,
};

View File

@ -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

View File

@ -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,

View File

@ -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);

View File

@ -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