From 93e9cf089eb244848b2a8e5c20f5205936d33ed2 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Sun, 10 Dec 2006 01:17:35 +0100 Subject: [PATCH] DOM: Change code documentation to be Doxygen "compliant" --- src/dom/code.h | 64 ++++++++++++++++++++------- src/dom/configuration.h | 12 +++--- src/dom/scanner.h | 33 +++++++------- src/dom/sgml/parser.h | 69 ++++++++++++++--------------- src/dom/stack.h | 96 +++++++++++++++++++++-------------------- 5 files changed, 156 insertions(+), 118 deletions(-) diff --git a/src/dom/code.h b/src/dom/code.h index 92de7fc85..3a58ca0f2 100644 --- a/src/dom/code.h +++ b/src/dom/code.h @@ -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, }; diff --git a/src/dom/configuration.h b/src/dom/configuration.h index ad0bdb319..f86898bf3 100644 --- a/src/dom/configuration.h +++ b/src/dom/configuration.h @@ -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 diff --git a/src/dom/scanner.h b/src/dom/scanner.h index 2a7e61b9b..1f6a6f17e 100644 --- a/src/dom/scanner.h +++ b/src/dom/scanner.h @@ -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, diff --git a/src/dom/sgml/parser.h b/src/dom/sgml/parser.h index 3d9393c74..4c338d505 100644 --- a/src/dom/sgml/parser.h +++ b/src/dom/sgml/parser.h @@ -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); diff --git a/src/dom/stack.h b/src/dom/stack.h index 0feeff73e..ca03b4141 100644 --- a/src/dom/stack.h +++ b/src/dom/stack.h @@ -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 + * 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