diff options
| author | Alex Valavanis <valavanisalex@gmail.com> | 2013-11-03 10:43:56 +0000 |
|---|---|---|
| committer | Alex Valavanis <valavanisalex@gmail.com> | 2013-11-03 10:43:56 +0000 |
| commit | 12b7ebd7b9f39010a6d93d56f2b3629d73c985a0 (patch) | |
| tree | b8c30f1cb703df6485a1c2367ca72a5b1e45dfc4 /src | |
| parent | Fix for Bug #1243394 (XAML exporter doesn't remove unnecessary filters attrib... (diff) | |
| download | inkscape-12b7ebd7b9f39010a6d93d56f2b3629d73c985a0.tar.gz inkscape-12b7ebd7b9f39010a6d93d56f2b3629d73c985a0.zip | |
Merge upstream libcroco 0.6.3 changes
(bzr r12765)
Diffstat (limited to 'src')
46 files changed, 2168 insertions, 1275 deletions
diff --git a/src/libcroco/cr-additional-sel.c b/src/libcroco/cr-additional-sel.c index 80a4767e0..7ed9e2c17 100644 --- a/src/libcroco/cr-additional-sel.c +++ b/src/libcroco/cr-additional-sel.c @@ -26,8 +26,21 @@ #include "string.h" /** - *Default constructor of #CRAdditionalSel. - *@return the newly build instance of #CRAdditionalSel. + * CRAdditionalSel: + * + * #CRAdditionalSel abstracts an additionnal selector. + * An additional selector is the selector part + * that comes after the combination of type selectors. + * It can be either "a class selector (the .class part), + * a pseudo class selector, an attribute selector + * or an id selector. + */ + +/** + * cr_additional_sel_new: + * + * Default constructor of #CRAdditionalSel. + * Returns the newly build instance of #CRAdditionalSel. */ CRAdditionalSel * cr_additional_sel_new (void) @@ -47,10 +60,12 @@ cr_additional_sel_new (void) } /** - *Constructor of #CRAdditionalSel. - *@param a_sel_type the type of the newly built instance - *of #CRAdditionalSel. - *@return the newly built instance of #CRAdditionalSel. + * cr_additional_sel_new_with_type: + * @a_sel_type: the type of the newly built instance + * of #CRAdditionalSel. + * + * Constructor of #CRAdditionalSel. + * Returns the newly built instance of #CRAdditionalSel. */ CRAdditionalSel * cr_additional_sel_new_with_type (enum AddSelectorType a_sel_type) @@ -67,12 +82,13 @@ cr_additional_sel_new_with_type (enum AddSelectorType a_sel_type) } /** - *Sets a new class name to a - *CLASS additional selector. - *@param a_this the "this pointer" of the current instance - *of #CRAdditionalSel . - *@param a_class_name the new class name to set. + * cr_additional_sel_set_class_name: + * @a_this: the "this pointer" of the current instance + * of #CRAdditionalSel . + * @a_class_name: the new class name to set. * + * Sets a new class name to a + * CLASS additional selector. */ void cr_additional_sel_set_class_name (CRAdditionalSel * a_this, @@ -88,11 +104,13 @@ cr_additional_sel_set_class_name (CRAdditionalSel * a_this, } /** - *Sets a new id name to an - *ID additional selector. - *@param a_this the "this pointer" of the current instance - *of #CRAdditionalSel . - *@param a_id the new id to set. + * cr_additional_sel_set_id_name: + * @a_this: the "this pointer" of the current instance + * of #CRAdditionalSel . + * @a_id: the new id to set. + * + * Sets a new id name to an + * ID additional selector. */ void cr_additional_sel_set_id_name (CRAdditionalSel * a_this, CRString * a_id) @@ -107,11 +125,13 @@ cr_additional_sel_set_id_name (CRAdditionalSel * a_this, CRString * a_id) } /** - *Sets a new pseudo to a - *PSEUDO additional selector. - *@param a_this the "this pointer" of the current instance - *of #CRAdditionalSel . - *@param a_pseudo the new pseudo to set. + * cr_additional_sel_set_pseudo: + * @a_this: the "this pointer" of the current instance + * of #CRAdditionalSel . + * @a_pseudo: the new pseudo to set. + * + * Sets a new pseudo to a + * PSEUDO additional selector. */ void cr_additional_sel_set_pseudo (CRAdditionalSel * a_this, CRPseudo * a_pseudo) @@ -127,11 +147,13 @@ cr_additional_sel_set_pseudo (CRAdditionalSel * a_this, CRPseudo * a_pseudo) } /** - *Sets a new instance of #CRAttrSel to - *a ATTRIBUTE additional selector. - *@param a_this the "this pointer" of the current instance - *of #CRAdditionalSel . - *@param a_sel the new instance of #CRAttrSel to set. + * cr_additional_sel_set_attr_sel: + * @a_this: the "this pointer" of the current instance + * of #CRAdditionalSel . + * @a_sel: the new instance of #CRAttrSel to set. + * + * Sets a new instance of #CRAttrSel to + * a ATTRIBUTE additional selector. */ void cr_additional_sel_set_attr_sel (CRAdditionalSel * a_this, CRAttrSel * a_sel) @@ -146,12 +168,15 @@ cr_additional_sel_set_attr_sel (CRAdditionalSel * a_this, CRAttrSel * a_sel) } /** - *Appends a new instance of #CRAdditional to the - *current list of #CRAdditional. - *@param a_this the "this pointer" of the current instance - *of #CRAdditionalSel . - *@param a_sel the new instance to #CRAdditional to append. - *@return the new list of CRAdditionalSel or NULL if an error arises. + * cr_additional_sel_append: + * @a_this: the "this pointer" of the current instance + * of #CRAdditionalSel . + * @a_sel: the new instance to #CRAdditional to append. + * + * Appends a new instance of #CRAdditional to the + * current list of #CRAdditional. + * + * Returns the new list of CRAdditionalSel or NULL if an error arises. */ CRAdditionalSel * cr_additional_sel_append (CRAdditionalSel * a_this, CRAdditionalSel * a_sel) @@ -179,12 +204,15 @@ cr_additional_sel_append (CRAdditionalSel * a_this, CRAdditionalSel * a_sel) } /** - *Preppends a new instance of #CRAdditional to the - *current list of #CRAdditional. - *@param a_this the "this pointer" of the current instance - *of #CRAdditionalSel . - *@param a_sel the new instance to #CRAdditional to preappend. - *@return the new list of CRAdditionalSel or NULL if an error arises. + * cr_additional_sel_prepend: + * @a_this: the "this pointer" of the current instance + * of #CRAdditionalSel . + * @a_sel: the new instance to #CRAdditional to preappend. + * + * Preppends a new instance of #CRAdditional to the + * current list of #CRAdditional. + * + * Returns the new list of CRAdditionalSel or NULL if an error arises. */ CRAdditionalSel * cr_additional_sel_prepend (CRAdditionalSel * a_this, CRAdditionalSel * a_sel) @@ -202,11 +230,11 @@ cr_additional_sel_prepend (CRAdditionalSel * a_this, CRAdditionalSel * a_sel) } guchar * -cr_additional_sel_to_string (CRAdditionalSel * a_this) +cr_additional_sel_to_string (CRAdditionalSel const * a_this) { guchar *result = NULL; GString *str_buf = NULL; - CRAdditionalSel *cur = NULL; + CRAdditionalSel const *cur = NULL; g_return_val_if_fail (a_this, NULL); @@ -304,7 +332,7 @@ cr_additional_sel_to_string (CRAdditionalSel * a_this) } guchar * -cr_additional_sel_one_to_string (CRAdditionalSel *a_this) +cr_additional_sel_one_to_string (CRAdditionalSel const *a_this) { guchar *result = NULL; GString *str_buf = NULL; @@ -403,13 +431,15 @@ cr_additional_sel_one_to_string (CRAdditionalSel *a_this) } /** - *Dumps the current instance of #CRAdditionalSel to a file - *@param a_this the "this pointer" of the current instance of - *#CRAdditionalSel. - *@param a_fp the destination file. + * cr_additional_sel_dump: + * @a_this: the "this pointer" of the current instance of + * #CRAdditionalSel. + * @a_fp: the destination file. + * + * Dumps the current instance of #CRAdditionalSel to a file */ void -cr_additional_sel_dump (CRAdditionalSel * a_this, FILE * a_fp) +cr_additional_sel_dump (CRAdditionalSel const * a_this, FILE * a_fp) { guchar *tmp_str = NULL; @@ -426,9 +456,11 @@ cr_additional_sel_dump (CRAdditionalSel * a_this, FILE * a_fp) } /** - *Destroys an instance of #CRAdditional. - *@param a_this the "this pointer" of the current instance - *of #CRAdditionalSel . + * cr_additional_sel_destroy: + * @a_this: the "this pointer" of the current instance + * of #CRAdditionalSel . + * + * Destroys an instance of #CRAdditional. */ void cr_additional_sel_destroy (CRAdditionalSel * a_this) diff --git a/src/libcroco/cr-additional-sel.h b/src/libcroco/cr-additional-sel.h index 1ec1aa0ec..7ca3e07d5 100644 --- a/src/libcroco/cr-additional-sel.h +++ b/src/libcroco/cr-additional-sel.h @@ -22,11 +22,6 @@ */ -/** - *@file - *This file holds the declaration of the - *#CRAddSel class. - */ #ifndef __CR_ADD_SEL_H__ #define __CR_ADD_SEL_H__ @@ -58,15 +53,6 @@ union CRAdditionalSelectorContent typedef struct _CRAdditionalSel CRAdditionalSel ; -/** - *#CRAdditionalSel abstracts - *an additionnal selector. - *An additional selector is the selector part - *that comes after the combination of type selectors. - *It can be either "a class selector (the .class part), - *a pseudo class selector, an attribute selector - *or an id selector. - */ struct _CRAdditionalSel { enum AddSelectorType type ; @@ -99,11 +85,11 @@ void cr_additional_sel_set_attr_sel (CRAdditionalSel *a_this, CRAdditionalSel * cr_additional_sel_prepend (CRAdditionalSel *a_this, CRAdditionalSel *a_sel) ; -guchar * cr_additional_sel_to_string (CRAdditionalSel *a_this) ; +guchar * cr_additional_sel_to_string (CRAdditionalSel const *a_this) ; -guchar * cr_additional_sel_one_to_string (CRAdditionalSel *a_this) ; +guchar * cr_additional_sel_one_to_string (CRAdditionalSel const *a_this) ; -void cr_additional_sel_dump (CRAdditionalSel *a_this, FILE *a_fp) ; +void cr_additional_sel_dump (CRAdditionalSel const *a_this, FILE *a_fp) ; void cr_additional_sel_destroy (CRAdditionalSel *a_this) ; diff --git a/src/libcroco/cr-attr-sel.c b/src/libcroco/cr-attr-sel.c index 0726f0f3e..7954290ac 100644 --- a/src/libcroco/cr-attr-sel.c +++ b/src/libcroco/cr-attr-sel.c @@ -24,17 +24,19 @@ #include "cr-attr-sel.h" /** - *@file - *The class that abstracts an attribute selector. - *Attributes selectors are described in the css2 spec [5.8]. - *There are more generally used in the css2 selectors described in - *css2 spec [5] . + * CRAttrSel: + * + * #CRAdditionalSel abstracts an attribute selector. + * Attributes selectors are described in the css2 spec [5.8]. + * There are more generally used in the css2 selectors described in + * css2 spec [5] . */ /** - *The constructor of #CRAttrSel. - *@return the newly allocated instance - *of #CRAttrSel. + * cr_attr_sel_new: + * The constructor of #CRAttrSel. + * Returns the newly allocated instance + * of #CRAttrSel. */ CRAttrSel * cr_attr_sel_new (void) @@ -45,13 +47,13 @@ cr_attr_sel_new (void) } /** - *Appends an attribute selector to the current list of - *attribute selectors represented by a_this. + * cr_attr_sel_append_attr_sel: + * @a_this: the this pointer of the current instance of #CRAttrSel. + * @a_attr_sel: selector to append. * - *@param a_this the this pointer of the current instance of - *#CRAttrSel. - *@param a_attr_sel selector to append. - *@return CR_OK upon successfull completion, an error code otherwise. + * Appends an attribute selector to the current list of + * attribute selectors represented by a_this. + * Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_attr_sel_append_attr_sel (CRAttrSel * a_this, CRAttrSel * a_attr_sel) @@ -72,13 +74,13 @@ cr_attr_sel_append_attr_sel (CRAttrSel * a_this, CRAttrSel * a_attr_sel) } /** + * cr_attr_sel_prepend_attr_sel: + *@a_this: the "this pointer" of the current instance *of #CRAttrSel. + *@a_attr_sel: the attribute selector to append. + * *Prepends an attribute selector to the list of *attributes selector represented by a_this. - * - *@param a_this the "this pointer" of the current instance - *of #CRAttrSel. - *@param a_attr_sel the attribute selector to append. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_attr_sel_prepend_attr_sel (CRAttrSel * a_this, @@ -93,10 +95,17 @@ cr_attr_sel_prepend_attr_sel (CRAttrSel * a_this, return CR_OK; } +/** + * cr_attr_sel_to_string: + * @a_this: the current instance of #CRAttrSel. + * + * Serializes an attribute selector into a string + * Returns the serialized attribute selector. + */ guchar * -cr_attr_sel_to_string (CRAttrSel * a_this) +cr_attr_sel_to_string (CRAttrSel const * a_this) { - CRAttrSel *cur = NULL; + CRAttrSel const *cur = NULL; guchar *result = NULL; GString *str_buf = NULL; @@ -161,13 +170,15 @@ cr_attr_sel_to_string (CRAttrSel * a_this) } /** - *Dumps the current instance of #CRAttrSel to a file. - *@param a_this the "this pointer" of the current instance of - *#CRAttrSel. - *@param a_fp the destination file. + * cr_attr_sel_dump: + * @a_this: the "this pointer" of the current instance of + * #CRAttrSel. + * @a_fp: the destination file. + * + * Dumps the current instance of #CRAttrSel to a file. */ void -cr_attr_sel_dump (CRAttrSel * a_this, FILE * a_fp) +cr_attr_sel_dump (CRAttrSel const * a_this, FILE * a_fp) { guchar *tmp_str = NULL; @@ -183,10 +194,12 @@ cr_attr_sel_dump (CRAttrSel * a_this, FILE * a_fp) } /** + *cr_attr_sel_destroy: + *@a_this: the "this pointer" of the current + *instance of #CRAttrSel. + * *Destroys the current instance of #CRAttrSel. *Frees all the fields if they are non null. - *@param a_this the "this pointer" of the current - *instance of #CRAttrSel. */ void cr_attr_sel_destroy (CRAttrSel * a_this) @@ -210,3 +223,4 @@ cr_attr_sel_destroy (CRAttrSel * a_this) g_free (a_this); } + diff --git a/src/libcroco/cr-attr-sel.h b/src/libcroco/cr-attr-sel.h index 9cc03d358..82d5a87d7 100644 --- a/src/libcroco/cr-attr-sel.h +++ b/src/libcroco/cr-attr-sel.h @@ -58,14 +58,14 @@ struct _CRAttrSel CRAttrSel * cr_attr_sel_new (void) ; enum CRStatus cr_attr_sel_append_attr_sel (CRAttrSel * a_this, - CRAttrSel *a_new) ; + CRAttrSel *a_attr_sel) ; enum CRStatus cr_attr_sel_prepend_attr_sel (CRAttrSel *a_this, CRAttrSel *a_attr_sel) ; -guchar * cr_attr_sel_to_string (CRAttrSel *a_this) ; +guchar * cr_attr_sel_to_string (CRAttrSel const *a_this) ; -void cr_attr_sel_dump (CRAttrSel *a_this, FILE *a_fp) ; +void cr_attr_sel_dump (CRAttrSel const *a_this, FILE *a_fp) ; void cr_attr_sel_destroy (CRAttrSel *a_this) ; diff --git a/src/libcroco/cr-cascade.c b/src/libcroco/cr-cascade.c index 7fef86c4a..9bdca07f3 100644 --- a/src/libcroco/cr-cascade.c +++ b/src/libcroco/cr-cascade.c @@ -44,6 +44,11 @@ struct _CRCascadePriv { }; /** + * cr_cascade_new: + *@a_author_sheet: the author origin style sheet. May be NULL. + *@a_user_sheet: the user origin style sheet. May be NULL. + *@a_ua_sheet: the user agent origin style sheet. May be NULL. + * *Constructor of the #CRCascade class. *Note that all three parameters of this *method are ref counted and their refcount is increased. @@ -51,10 +56,8 @@ struct _CRCascadePriv { *the instance of #CRCascade. *So the caller should not call their destructor. The caller *should call their ref/unref method instead if it wants - *@param a_author_sheet the autor origin style sheet - *@param a_user_sheet the user origin style sheet. - *@param a_ua_sheet the user agent origin style sheet. - *@return the newly built instance of CRCascade or NULL if + * + *Returns the newly built instance of CRCascade or NULL if *an error arose during constrution. */ CRCascade * @@ -90,16 +93,19 @@ cr_cascade_new (CRStyleSheet * a_author_sheet, } /** + * cr_cascade_get_sheet: + *@a_this: the current instance of #CRCascade. + *@a_origin: the origin of the style sheet as + *defined in the css2 spec in chapter 6.4. *Gets a given origin sheet. + * + *Gets a sheet, part of the cascade. *Note that the returned stylesheet *is refcounted so if the caller wants *to manage its lifecycle, it must use *cr_stylesheet_ref()/cr_stylesheet_unref() instead *of the cr_stylesheet_destroy() method. - *@param a_this the current instance of #CRCascade. - *@param a_origin the origin of the style sheet as - *defined in the css2 spec in chapter 6.4. - *@return the style sheet, or NULL if it does not + *Returns the style sheet, or NULL if it does not *exist. */ CRStyleSheet * @@ -112,11 +118,14 @@ cr_cascade_get_sheet (CRCascade * a_this, enum CRStyleOrigin a_origin) } /** + * cr_cascade_set_sheet: + *@a_this: the current instance of #CRCascade. + *@a_sheet: the stylesheet to set. + *@a_origin: the origin of the stylesheet. + * *Sets a stylesheet in the cascade - *@param a_this the current instance of #CRCascade. - *@param a_sheet the stylesheet to set. - *@param a_origin the origin of the stylesheet. - *@return CR_OK upon successfull completion, an error + * + *Returns CR_OK upon successfull completion, an error *code otherwise. */ enum CRStatus @@ -136,10 +145,11 @@ cr_cascade_set_sheet (CRCascade * a_this, } /** + *cr_cascade_ref: + *@a_this: the current instance of #CRCascade + * *Increases the reference counter of the current instance *of #CRCascade. - *@param a_this the current instance of #CRCascade - * */ void cr_cascade_ref (CRCascade * a_this) @@ -150,12 +160,14 @@ cr_cascade_ref (CRCascade * a_this) } /** + * cr_cascade_unref: + *@a_this: the current instance of + *#CRCascade. + * *Decrements the reference counter associated *to this instance of #CRCascade. If the reference *counter reaches zero, the instance is destroyed *using cr_cascade_destroy() - *@param a_this the current instance of - *#CRCascade. */ void cr_cascade_unref (CRCascade * a_this) @@ -170,7 +182,10 @@ cr_cascade_unref (CRCascade * a_this) } /** - *Destructor of #CRCascade. + * cr_cascade_destroy: + * @a_this: the current instance of #CRCascade + * + * Destructor of #CRCascade. */ void cr_cascade_destroy (CRCascade * a_this) diff --git a/src/libcroco/cr-declaration.c b/src/libcroco/cr-declaration.c index 530085b52..9f280837c 100644 --- a/src/libcroco/cr-declaration.c +++ b/src/libcroco/cr-declaration.c @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -28,18 +28,21 @@ #include "cr-parser.h" /** - *@file + *@CRDeclaration: + * *The definition of the #CRDeclaration class. */ /** + * dump: + *@a_this: the current instance of #CRDeclaration. + *@a_fp: the destination file pointer. + *@a_indent: the number of indentation white char. + * *Dumps (serializes) one css declaration to a file. - *@param a_this the current instance of #CRDeclaration. - *@param a_fp the destination file pointer. - *@param a_indent the number of indentation white char. */ static void -dump (CRDeclaration * a_this, FILE * a_fp, glong a_indent) +dump (CRDeclaration const * a_this, FILE * a_fp, glong a_indent) { g_return_if_fail (a_this); @@ -52,11 +55,18 @@ dump (CRDeclaration * a_this, FILE * a_fp, glong a_indent) } /** + * cr_declaration_new: + * @a_statement: the statement this declaration belongs to. can be NULL. + *@a_property: the property string of the declaration + *@a_value: the value expression of the declaration. *Constructor of #CRDeclaration. - *@param a_property the property string of the declaration - *@param a_value the value expression of the declaration. - *@return the newly built instance of #CRDeclaration, or NULL in + * + *Returns the newly built instance of #CRDeclaration, or NULL in *case of error. + * + *The returned CRDeclaration takes ownership of @a_property and @a_value. + *(E.g. cr_declaration_destroy on this CRDeclaration will also free + *@a_property and @a_value.) */ CRDeclaration * cr_declaration_new (CRStatement * a_statement, @@ -89,15 +99,16 @@ cr_declaration_new (CRStatement * a_statement, } /** - *Parses a text buffer that contains - *a css declaration. - * - *@param a_statement the parent css2 statement of this + * cr_declaration_parse_from_buf: + *@a_statement: the parent css2 statement of this *this declaration. Must be non NULL and of type *RULESET_STMT (must be a ruleset). - *@param a_str the string that contains the statement. - *@param a_enc the encoding of a_str. - *@return the parsed declaration, or NULL in case of error. + *@a_str: the string that contains the statement. + *@a_enc: the encoding of a_str. + * + *Parses a text buffer that contains + *a css declaration. + *Returns the parsed declaration, or NULL in case of error. */ CRDeclaration * cr_declaration_parse_from_buf (CRStatement * a_statement, @@ -156,11 +167,13 @@ cr_declaration_parse_from_buf (CRStatement * a_statement, } /** - *Parses a ';' separated list of properties declaration. - *@param a_str the input buffer that contains the list of declaration to + * cr_declaration_parse_list_from_buf: + *@a_str: the input buffer that contains the list of declaration to *parse. - *@param a_enc the encoding of a_str - *@return the parsed list of declaration, NULL if parsing failed. + *@a_enc: the encoding of a_str + * + *Parses a ';' separated list of properties declaration. + *Returns the parsed list of declaration, NULL if parsing failed. */ CRDeclaration * cr_declaration_parse_list_from_buf (const guchar * a_str, @@ -269,10 +282,12 @@ cr_declaration_parse_list_from_buf (const guchar * a_str, } /** + * cr_declaration_append: + *@a_this: the current declaration list. + *@a_new: the declaration to append. + * *Appends a new declaration to the current declarations list. - *@param a_this the current declaration list. - *@param a_new the declaration to append. - *@return the declaration list with a_new appended to it, or NULL + *Returns the declaration list with a_new appended to it, or NULL *in case of error. */ CRDeclaration * @@ -294,10 +309,13 @@ cr_declaration_append (CRDeclaration * a_this, CRDeclaration * a_new) } /** + * cr_declaration_unlink: + *@a_decls: the declaration to unlink. + * *Unlinks the declaration from the declaration list. - *@param a_decl the declaration to unlink. - *@return a pointer to the unlinked declaration in *case of a successfull completion, NULL otherwise. + * + *Returns a pointer to the unlinked declaration in */ CRDeclaration * cr_declaration_unlink (CRDeclaration * a_decl) @@ -369,10 +387,13 @@ cr_declaration_unlink (CRDeclaration * a_decl) } /** - *prepends a declaration to the current declaration list. - *@param a_this the current declaration list. - *@param a_new the declaration to prepend. - *@return the list with a_new prepended or NULL in case of error. + * cr_declaration_prepend: + * @a_this: the current declaration list. + * @a_new: the declaration to prepend. + * + * prepends a declaration to the current declaration list. + * + * Returns the list with a_new prepended or NULL in case of error. */ CRDeclaration * cr_declaration_prepend (CRDeclaration * a_this, CRDeclaration * a_new) @@ -393,11 +414,13 @@ cr_declaration_prepend (CRDeclaration * a_this, CRDeclaration * a_new) } /** + * cr_declaration_append2: + *@a_this: the current declaration list. + *@a_prop: the property string of the declaration to append. + *@a_value: the value of the declaration to append. + * *Appends a declaration to the current declaration list. - *@param a_this the current declaration list. - *@param a_prop the property string of the declaration to append. - *@param a_value the value of the declaration to append. - *@return the list with the new property appended to it, or NULL in + *Returns the list with the new property appended to it, or NULL in *case of an error. */ CRDeclaration * @@ -419,16 +442,20 @@ cr_declaration_append2 (CRDeclaration * a_this, } /** + * cr_declaration_dump: + *@a_this: the current instance of #CRDeclaration. + *@a_fp: the destination file. + *@a_indent: the number of indentation white char. + *@a_one_per_line: whether to put one declaration per line of not . + * + * *Dumps a declaration list to a file. - *@param a_this the current instance of #CRDeclaration. - *@param a_fp the destination file. - *@param a_indent the number of indentation white char. */ void -cr_declaration_dump (CRDeclaration * a_this, FILE * a_fp, glong a_indent, +cr_declaration_dump (CRDeclaration const * a_this, FILE * a_fp, glong a_indent, gboolean a_one_per_line) { - CRDeclaration *cur = NULL; + CRDeclaration const *cur = NULL; g_return_if_fail (a_this); @@ -444,13 +471,15 @@ cr_declaration_dump (CRDeclaration * a_this, FILE * a_fp, glong a_indent, } /** + * cr_declaration_dump_one: + *@a_this: the current instance of #CRDeclaration. + *@a_fp: the destination file. + *@a_indent: the number of indentation white char. + * *Dumps the first declaration of the declaration list to a file. - *@param a_this the current instance of #CRDeclaration. - *@param a_fp the destination file. - *@param a_indent the number of indentation white char. */ void -cr_declaration_dump_one (CRDeclaration * a_this, FILE * a_fp, glong a_indent) +cr_declaration_dump_one (CRDeclaration const * a_this, FILE * a_fp, glong a_indent) { g_return_if_fail (a_this); @@ -458,13 +487,17 @@ cr_declaration_dump_one (CRDeclaration * a_this, FILE * a_fp, glong a_indent) } /** - *Serializes the declaration into a string - *@param a_this the current instance of #CRDeclaration. - *@param a_indent the number of indentation white char + * cr_declaration_to_string: + *@a_this: the current instance of #CRDeclaration. + *@a_indent: the number of indentation white char *to put before the actual serialisation. + * + *Serializes the declaration into a string + *Returns the serialized form the declaration. The caller must + *free the string using g_free(). */ gchar * -cr_declaration_to_string (CRDeclaration * a_this, gulong a_indent) +cr_declaration_to_string (CRDeclaration const * a_this, gulong a_indent) { GString *stringue = NULL; @@ -525,15 +558,17 @@ cr_declaration_to_string (CRDeclaration * a_this, gulong a_indent) } /** - *Serializes the declaration list into a string - *@param a_this the current instance of #CRDeclaration. - *@param a_indent the number of indentation white char + * cr_declaration_list_to_string: + *@a_this: the current instance of #CRDeclaration. + *@a_indent: the number of indentation white char *to put before the actual serialisation. + * + *Serializes the declaration list into a string */ guchar * -cr_declaration_list_to_string (CRDeclaration * a_this, gulong a_indent) +cr_declaration_list_to_string (CRDeclaration const * a_this, gulong a_indent) { - CRDeclaration *cur = NULL; + CRDeclaration const *cur = NULL; GString *stringue = NULL; gchar *str = NULL, *result = NULL; @@ -559,16 +594,20 @@ cr_declaration_list_to_string (CRDeclaration * a_this, gulong a_indent) } /** - *Serializes the declaration list into a string - *@param a_this the current instance of #CRDeclaration. - *@param a_indent the number of indentation white char + * cr_declaration_list_to_string2: + *@a_this: the current instance of #CRDeclaration. + *@a_indent: the number of indentation white char + *@a_one_decl_per_line: whether to output one doc per line or not. *to put before the actual serialisation. + * + *Serializes the declaration list into a string + *Returns the serialized form the declararation. */ guchar * -cr_declaration_list_to_string2 (CRDeclaration * a_this, +cr_declaration_list_to_string2 (CRDeclaration const * a_this, gulong a_indent, gboolean a_one_decl_per_line) { - CRDeclaration *cur = NULL; + CRDeclaration const *cur = NULL; GString *stringue = NULL; gchar *str = NULL, *result = NULL; @@ -608,14 +647,14 @@ cr_declaration_list_to_string2 (CRDeclaration * a_this, } /** - *Return the number of properties in the declaration; - *@param a_this the current instance of #CRDeclaration. - *@return number of properties in the declaration list. + * cr_declaration_nr_props: + *@a_this: the current instance of #CRDeclaration. + *Return the number of properties in the declaration */ gint -cr_declaration_nr_props (CRDeclaration * a_this) +cr_declaration_nr_props (CRDeclaration const * a_this) { - CRDeclaration *cur = NULL; + CRDeclaration const *cur = NULL; int nr = 0; g_return_val_if_fail (a_this, -1); @@ -626,10 +665,14 @@ cr_declaration_nr_props (CRDeclaration * a_this) } /** + * cr_declaration_get_from_list: + *@a_this: the current instance of #CRDeclaration. + *@itemnr: the index into the declaration list. + * *Use an index to get a CRDeclaration from the declaration list. - *@param a_this the current instance of #CRDeclaration. - *@param itemnr the index into the declaration list. - *@return CRDeclaration at position itemnr, if itemnr > number of declarations - 1, + * + *Returns #CRDeclaration at position itemnr, + *if itemnr > number of declarations - 1, *it will return NULL. */ CRDeclaration * @@ -647,10 +690,12 @@ cr_declaration_get_from_list (CRDeclaration * a_this, int itemnr) } /** + * cr_declaration_get_by_prop_name: + *@a_this: the current instance of #CRDeclaration. + *@a_prop: the property name to search for. + * *Use property name to get a CRDeclaration from the declaration list. - *@param a_this the current instance of #CRDeclaration. - *@param a_prop the property name to search for. - *@return CRDeclaration with property name a_prop, or NULL if not found. + *Returns #CRDeclaration with property name a_prop, or NULL if not found. */ CRDeclaration * cr_declaration_get_by_prop_name (CRDeclaration * a_this, @@ -675,8 +720,10 @@ cr_declaration_get_by_prop_name (CRDeclaration * a_this, } /** + * cr_declaration_ref: + *@a_this: the current instance of #CRDeclaration. + * *Increases the ref count of the current instance of #CRDeclaration. - *@param a_this the current instance of #CRDeclaration. */ void cr_declaration_ref (CRDeclaration * a_this) @@ -687,12 +734,14 @@ cr_declaration_ref (CRDeclaration * a_this) } /** + * cr_declaration_unref: + *@a_this: the current instance of #CRDeclaration. + * *Decrements the ref count of the current instance of #CRDeclaration. *If the ref count reaches zero, the current instance of #CRDeclaration *if destroyed. - *@param a_this the current instance of #CRDeclaration. - *@return TRUE if the current instance of #CRDeclaration has been destroyed - *(ref count reached zero), FALSE otherwise. + *Returns TRUE if @a_this was destroyed (ref count reached zero), + *FALSE otherwise. */ gboolean cr_declaration_unref (CRDeclaration * a_this) @@ -711,8 +760,10 @@ cr_declaration_unref (CRDeclaration * a_this) } /** + * cr_declaration_destroy: + *@a_this: the current instance of #CRDeclaration. + * *Destructor of the declaration list. - *@param a_this the current instance of #CRDeclaration. */ void cr_declaration_destroy (CRDeclaration * a_this) @@ -722,22 +773,19 @@ cr_declaration_destroy (CRDeclaration * a_this) g_return_if_fail (a_this); /* - *Go get the tail of the list. - *Meanwhile, free each property/value pair contained in the list. + * Go to the last element of the list. */ - for (cur = a_this; cur && cur->next; cur = cur->next) { - if (cur->property) { - cr_string_destroy (cur->property); - cur->property = NULL; - } + for (cur = a_this; cur->next; cur = cur->next) + g_assert (cur->next->prev == cur); - if (cur->value) { - cr_term_destroy (cur->value); - cur->value = NULL; - } - } + /* + * Walk backward the list and free each "next" element. + * Meanwhile, free each property/value pair contained in the list. + */ + for (; cur; cur = cur->prev) { + g_free (cur->next); + cur->next = NULL; - if (cur) { if (cur->property) { cr_string_destroy (cur->property); cur->property = NULL; @@ -749,27 +797,5 @@ cr_declaration_destroy (CRDeclaration * a_this) } } - /*in case the list contains only one element */ - if (cur && !cur->prev) { - g_free (cur); - return; - } - - /*walk backward the list and free each "next" element */ - for (cur = cur->prev; cur && cur->prev; cur = cur->prev) { - if (cur->next) { - g_free (cur->next); - cur->next = NULL; - } - } - - if (!cur) - return; - - if (cur->next) { - g_free (cur->next); - cur->next = NULL; - } - - g_free (cur); + g_free (a_this); } diff --git a/src/libcroco/cr-declaration.h b/src/libcroco/cr-declaration.h index 00523956c..eee8be321 100644 --- a/src/libcroco/cr-declaration.h +++ b/src/libcroco/cr-declaration.h @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -100,14 +100,14 @@ CRDeclaration * cr_declaration_prepend (CRDeclaration *a_this, CRDeclaration * cr_declaration_unlink (CRDeclaration * a_decl) ; void -cr_declaration_dump (CRDeclaration *a_this, +cr_declaration_dump (CRDeclaration const *a_this, FILE *a_fp, glong a_indent, gboolean a_one_per_line) ; -void cr_declaration_dump_one (CRDeclaration *a_this, +void cr_declaration_dump_one (CRDeclaration const *a_this, FILE *a_fp, glong a_indent) ; -gint cr_declaration_nr_props (CRDeclaration *a_this) ; +gint cr_declaration_nr_props (CRDeclaration const *a_this) ; CRDeclaration * cr_declaration_get_from_list (CRDeclaration *a_this, int itemnr) ; @@ -115,13 +115,13 @@ CRDeclaration * cr_declaration_get_from_list (CRDeclaration *a_this, CRDeclaration * cr_declaration_get_by_prop_name (CRDeclaration *a_this, const guchar *a_str) ; -gchar * cr_declaration_to_string (CRDeclaration *a_this, +gchar * cr_declaration_to_string (CRDeclaration const *a_this, gulong a_indent) ; -guchar * cr_declaration_list_to_string (CRDeclaration *a_this, +guchar * cr_declaration_list_to_string (CRDeclaration const *a_this, gulong a_indent) ; -guchar * cr_declaration_list_to_string2 (CRDeclaration *a_this, +guchar * cr_declaration_list_to_string2 (CRDeclaration const *a_this, gulong a_indent, gboolean a_one_decl_per_line) ; diff --git a/src/libcroco/cr-doc-handler.c b/src/libcroco/cr-doc-handler.c index 00357c0f0..b76ba5515 100644 --- a/src/libcroco/cr-doc-handler.c +++ b/src/libcroco/cr-doc-handler.c @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -25,7 +25,8 @@ #include "cr-parser.h" /** - *@file + *@CRDocHandler: + * *The definition of the CRDocHandler class. *Contains methods to instantiate, destroy, *and initialyze instances of #CRDocHandler @@ -58,9 +59,12 @@ struct _CRDocHandlerPriv { }; /** + * cr_doc_handler_new: *Constructor of #CRDocHandler. - *@return the newly built instance of + * + *Returns the newly built instance of *#CRDocHandler + * */ CRDocHandler * cr_doc_handler_new (void) @@ -70,6 +74,7 @@ cr_doc_handler_new (void) g_return_val_if_fail (result, NULL); memset (result, 0, sizeof (CRDocHandler)); + result->ref_count++; result->priv = (CRDocHandlerPriv *)g_try_malloc (sizeof (CRDocHandlerPriv)); if (!result->priv) { @@ -84,15 +89,17 @@ cr_doc_handler_new (void) } /** - *Returns the private parsing context. + * cr_doc_handler_get_ctxt: + *@a_this: the current instance of #CRDocHandler. + *@a_ctxt: out parameter. The new parsing context. + * + *Gets the private parsing context associated to the document handler *The private parsing context is used by libcroco only. - *@param a_this the current instance of #CRDocHandler. - *@param a_ctxt out parameter. The new parsing context. - *@return CR_OK upon successfull completion, an error code otherwise. - *@return the parsing context, or NULL if an error occured. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus -cr_doc_handler_get_ctxt (CRDocHandler * a_this, gpointer * a_ctxt) +cr_doc_handler_get_ctxt (CRDocHandler const * a_this, gpointer * a_ctxt) { g_return_val_if_fail (a_this && a_this->priv, CR_BAD_PARAM_ERROR); @@ -102,11 +109,13 @@ cr_doc_handler_get_ctxt (CRDocHandler * a_this, gpointer * a_ctxt) } /** + * cr_doc_handler_set_ctxt: + *@a_this: the current instance of #CRDocHandler + *@a_ctxt: a pointer to the parsing context. + * *Sets the private parsing context. *This is used by libcroco only. - *@param a_this the current instance of #CRDocHandler - *@param a_ctxt a pointer to the parsing context. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_doc_handler_set_ctxt (CRDocHandler * a_this, gpointer a_ctxt) @@ -117,14 +126,17 @@ cr_doc_handler_set_ctxt (CRDocHandler * a_this, gpointer a_ctxt) } /** - *Returns the private parsing result. + * cr_doc_handler_get_result: + *@a_this: the current instance of #CRDocHandler + *@a_result: out parameter. The returned result. + * + *Gets the private parsing result. *The private parsing result is used by libcroco only. - *@param a_this the current instance of #CRDocHandler - *@param a_result out parameter. The returned result. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus -cr_doc_handler_get_result (CRDocHandler * a_this, gpointer * a_result) +cr_doc_handler_get_result (CRDocHandler const * a_this, gpointer * a_result) { g_return_val_if_fail (a_this && a_this->priv, CR_BAD_PARAM_ERROR); @@ -134,11 +146,14 @@ cr_doc_handler_get_result (CRDocHandler * a_this, gpointer * a_result) } /** + * cr_doc_handler_set_result: + *@a_this: the current instance of #CRDocHandler + *@a_result: the new result. + * *Sets the private parsing context. *This is used by libcroco only. - *@param a_this the current instance of #CRDocHandler - *@param a_result the new result. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_doc_handler_set_result (CRDocHandler * a_this, gpointer a_result) @@ -149,14 +164,16 @@ cr_doc_handler_set_result (CRDocHandler * a_this, gpointer a_result) } /** + *cr_doc_handler_set_default_sac_handler: + *@a_this: a pointer to the current instance of #CRDocHandler. + * *Sets the sac handlers contained in the current *instance of DocHandler to the default handlers. *For the time being the default handlers are *test handlers. This is expected to change in a *near future, when the libcroco gets a bit debugged. * - *@param a_this a pointer to the current instance of #CRDocHandler. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_doc_handler_set_default_sac_handler (CRDocHandler * a_this) @@ -184,8 +201,8 @@ cr_doc_handler_set_default_sac_handler (CRDocHandler * a_this) } /** - *Increases the reference count of the doc handler - *@param a_this the current instance of #CRDocHandler. + * cr_doc_handler_ref: + *@a_this: the current instance of #CRDocHandler. */ void cr_doc_handler_ref (CRDocHandler * a_this) @@ -196,10 +213,13 @@ cr_doc_handler_ref (CRDocHandler * a_this) } /** + * cr_doc_handler_unref: + *@a_this: the currrent instance of #CRDocHandler. + * *Decreases the ref count of the current instance of #CRDocHandler. *If the ref count reaches '0' then, destroys the instance. - *@param a_this the currrent instance of #CRDocHandler. - *@return TRUE if the instance as been destroyed, FALSE otherwise. + * + *Returns TRUE if the instance as been destroyed, FALSE otherwise. */ gboolean cr_doc_handler_unref (CRDocHandler * a_this) @@ -218,9 +238,11 @@ cr_doc_handler_unref (CRDocHandler * a_this) } /** - *The destructor of the #CRDocHandler class. - *@param a_this the instance of #CRDocHandler to + * cr_doc_handler_destroy: + *@a_this: the instance of #CRDocHandler to *destroy. + * + *The destructor of the #CRDocHandler class. */ void cr_doc_handler_destroy (CRDocHandler * a_this) @@ -235,9 +257,11 @@ cr_doc_handler_destroy (CRDocHandler * a_this) } /** + * cr_doc_handler_associate_a_parser: *Associates a parser to the current document handler - *@param a_this the current instance of document handler. - *@param a_parser the parser to associate. + * + *@a_this: the current instance of document handler. + *@a_parser: the parser to associate. */ void cr_doc_handler_associate_a_parser (CRDocHandler *a_this, diff --git a/src/libcroco/cr-doc-handler.h b/src/libcroco/cr-doc-handler.h index 704f186f5..d12673f31 100644 --- a/src/libcroco/cr-doc-handler.h +++ b/src/libcroco/cr-doc-handler.h @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -92,7 +92,7 @@ struct _CRDocHandler *destination media for style information. *@param a_uri the uri of the imported style sheet. *@param a_uri_default_ns the default namespace of URI - *@param a_location the parsing location of the '@import' + *@param a_location the parsing location of the '\@import' *keyword. *of the imported style sheet. */ @@ -175,7 +175,7 @@ struct _CRDocHandler * *@param a_this a pointer to the current instance of *#CRDocHandler. - *@param a_location the parsing location of the "@font-face" + *@param a_location the parsing location of the "\@font-face" *keyword. */ void (*start_font_face) (CRDocHandler *a_this, @@ -227,7 +227,7 @@ struct _CRDocHandler *#CRDocHandler. *@param a_name the name of the page (if any, null otherwise). *@param a_pseudo_page the pseudo page (if any, null otherwise). - *@param a_location the parsing location of the "@page" keyword. + *@param a_location the parsing location of the "\@page" keyword. */ void (*start_page) (CRDocHandler *a_this, CRString *a_name, @@ -239,7 +239,7 @@ struct _CRDocHandler *@param a_this a pointer to the current instance of *#CRDocHandler. *@param a_name the name of the page (if any, null otherwise). - *@parap a_pseudo_page the pseudo page (if any, null otherwise). + *@param a_pseudo_page the pseudo page (if any, null otherwise). */ void (*end_page) (CRDocHandler *a_this, CRString *a_name, @@ -276,11 +276,11 @@ CRDocHandler * cr_doc_handler_new (void) ; enum CRStatus cr_doc_handler_set_result (CRDocHandler *a_this, gpointer a_result) ; -enum CRStatus cr_doc_handler_get_result (CRDocHandler *a_this, gpointer * a_result) ; +enum CRStatus cr_doc_handler_get_result (CRDocHandler const *a_this, gpointer * a_result) ; enum CRStatus cr_doc_handler_set_ctxt (CRDocHandler *a_this, gpointer a_ctxt) ; -enum CRStatus cr_doc_handler_get_ctxt (CRDocHandler *a_this, gpointer * a_ctxt) ; +enum CRStatus cr_doc_handler_get_ctxt (CRDocHandler const *a_this, gpointer * a_ctxt) ; enum CRStatus cr_doc_handler_set_default_sac_handler (CRDocHandler *a_this) ; diff --git a/src/libcroco/cr-enc-handler.c b/src/libcroco/cr-enc-handler.c index 973a5f373..993254a33 100644 --- a/src/libcroco/cr-enc-handler.c +++ b/src/libcroco/cr-enc-handler.c @@ -74,10 +74,13 @@ static CREncHandler gv_default_enc_handlers[] = { }; /** + * cr_enc_handler_get_instance: + *@a_enc: the encoding of the Handler. + * *Gets the instance of encoding handler. *This function implements a singleton pattern. - *@param a_enc the encoding of the Handler. - *@return the instance of #CREncHandler. + * + *Returns the instance of #CREncHandler. */ CREncHandler * cr_enc_handler_get_instance (enum CREncoding a_enc) @@ -95,12 +98,15 @@ cr_enc_handler_get_instance (enum CREncoding a_enc) } /** + * cr_enc_handler_resolve_enc_alias: + *@a_alias_name: the encoding name. + *@a_enc: output param. The returned encoding type + *or 0 if the alias is not supported. + * *Given an encoding name (called an alias name) *the function returns the matching encoding type. - *@param a_alias_name the encoding name - *@param a_enc output param. The returned encoding type - *or 0 if the alias is not supported. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_enc_handler_resolve_enc_alias (const guchar * a_alias_name, @@ -126,16 +132,19 @@ cr_enc_handler_resolve_enc_alias (const guchar * a_alias_name, } /** - *Converts a raw input buffer into an utf8 buffer. - *@param a_this the current instance of #CREncHandler. - *@param a_in the input buffer to convert. - *@param a_in_len in/out parameter. The len of the input + * cr_enc_handler_convert_input: + *@a_this: the current instance of #CREncHandler. + *@a_in: the input buffer to convert. + *@a_in_len: in/out parameter. The len of the input *buffer to convert. After return, contains the number of *bytes actually consumed. - *@param @a_out output parameter. The converted output buffer. + *@a_out: output parameter. The converted output buffer. *Must be freed by the buffer. - *@param a_out_len output parameter. The length of the output buffer. - *@return CR_OK upon successfull completion, an error code otherwise. + *@a_out_len: output parameter. The length of the output buffer. + * + *Converts a raw input buffer into an utf8 buffer. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_enc_handler_convert_input (CREncHandler * a_this, diff --git a/src/libcroco/cr-enc-handler.h b/src/libcroco/cr-enc-handler.h index 2f5da69f9..63e7433ef 100644 --- a/src/libcroco/cr-enc-handler.h +++ b/src/libcroco/cr-enc-handler.h @@ -79,10 +79,8 @@ CREncHandler * cr_enc_handler_get_instance (enum CREncoding a_enc) ; enum CRStatus -cr_enc_handler_resolve_enc_alias (const guchar *a_en_alias, +cr_enc_handler_resolve_enc_alias (const guchar *a_alias_name, enum CREncoding *a_enc) ; -void -cr_enc_handler_destroy (CREncHandler * a_enc_hdlr) ; enum CRStatus cr_enc_handler_convert_input (CREncHandler *a_this, diff --git a/src/libcroco/cr-fonts.c b/src/libcroco/cr-fonts.c index 14438c344..96a8e1cee 100644 --- a/src/libcroco/cr-fonts.c +++ b/src/libcroco/cr-fonts.c @@ -27,10 +27,10 @@ #include <string.h> static enum CRStatus -cr_font_family_to_string_real (CRFontFamily * a_this, +cr_font_family_to_string_real (CRFontFamily const * a_this, gboolean a_walk_list, GString ** a_string) { - gchar *name = NULL; + gchar const *name = NULL; enum CRStatus result = CR_OK; if (!*a_string) { @@ -46,31 +46,31 @@ cr_font_family_to_string_real (CRFontFamily * a_this, switch (a_this->type) { case FONT_FAMILY_SANS_SERIF: - name = (gchar *) "sans-serif"; + name = (gchar const *) "sans-serif"; break; case FONT_FAMILY_SERIF: - name = (gchar *) "sans-serif"; + name = (gchar const *) "sans-serif"; break; case FONT_FAMILY_CURSIVE: - name = (gchar *) "cursive"; + name = (gchar const *) "cursive"; break; case FONT_FAMILY_FANTASY: - name = (gchar *) "fantasy"; + name = (gchar const *) "fantasy"; break; case FONT_FAMILY_MONOSPACE: - name = (gchar *) "monospace"; + name = (gchar const *) "monospace"; break; case FONT_FAMILY_NON_GENERIC: - name = (gchar *) a_this->name; + name = (gchar const *) a_this->name; break; default: - name = (gchar *) NULL; + name = NULL; break; } @@ -92,32 +92,32 @@ static const gchar * cr_predefined_absolute_font_size_to_string (enum CRPredefinedAbsoluteFontSize a_code) { - gchar *str = NULL; + gchar const *str = NULL; switch (a_code) { case FONT_SIZE_XX_SMALL: - str = (gchar *) "xx-small"; + str = "xx-small"; break; case FONT_SIZE_X_SMALL: - str = (gchar *) "x-small"; + str = "x-small"; break; case FONT_SIZE_SMALL: - str = (gchar *) "small"; + str = "small"; break; case FONT_SIZE_MEDIUM: - str = (gchar *) "medium"; + str = "medium"; break; case FONT_SIZE_LARGE: - str = (gchar *) "large"; + str = "large"; break; case FONT_SIZE_X_LARGE: - str = (gchar *) "x-large"; + str = "x-large"; break; case FONT_SIZE_XX_LARGE: - str = (gchar *) "xx-large"; + str = "xx-large"; break; default: - str = (gchar *) "unknown absolute font size value"; + str = "unknown absolute font size value"; } return str; } @@ -125,22 +125,31 @@ cr_predefined_absolute_font_size_to_string (enum CRPredefinedAbsoluteFontSize static const gchar * cr_relative_font_size_to_string (enum CRRelativeFontSize a_code) { - gchar *str = NULL; + gchar const *str = NULL; switch (a_code) { case FONT_SIZE_LARGER: - str = (gchar *) "larger"; + str = "larger"; break; case FONT_SIZE_SMALLER: - str = (gchar *) "smaller"; + str = "smaller"; break; default: - str = (gchar *) "unknown relative font size value"; + str = "unknown relative font size value"; break; } return str; } +/** + * cr_font_family_new: + * @a_type: the type of font family to create. + * @a_name: the name of the font family. + * + * create a font family. + * + * Returns the newly built font family. + */ CRFontFamily * cr_font_family_new (enum CRFontFamilyType a_type, guchar * a_name) { @@ -159,8 +168,16 @@ cr_font_family_new (enum CRFontFamilyType a_type, guchar * a_name) return result; } +/** + * cr_font_family_to_string: + * @a_this: the current instance of #CRFontFamily. + * @a_walk_font_family_list: wether the serialize the entire list. + * + * Returns the seriliazed font family. The caller has to free it using + * g_free(). + */ guchar * -cr_font_family_to_string (CRFontFamily * a_this, +cr_font_family_to_string (CRFontFamily const * a_this, gboolean a_walk_font_family_list) { enum CRStatus status = CR_OK; @@ -190,6 +207,14 @@ cr_font_family_to_string (CRFontFamily * a_this, return (guchar *)result; } + +/** + * cr_font_family_set_name: + * @a_this: the current instance of #CRFontFamily. + * @a_name: the new name + * + * Returns CR_OK upon sucessful completion, an error code otherwise. + */ enum CRStatus cr_font_family_set_name (CRFontFamily * a_this, guchar * a_name) { @@ -212,6 +237,13 @@ cr_font_family_set_name (CRFontFamily * a_this, guchar * a_name) return CR_OK; } +/** + * cr_font_family_append: + * @a_this: the current instance of #CRFontFamily. + * @a_family_to_append: the font family to append to the list + * + * Returns the new font family list. + */ CRFontFamily * cr_font_family_append (CRFontFamily * a_this, CRFontFamily * a_family_to_append) @@ -232,6 +264,13 @@ cr_font_family_append (CRFontFamily * a_this, } +/** + * cr_font_family_prepend: + * @a_this: the current instance #CRFontFamily. + * @a_family_to_prepend: the font family to prepend to the list. + * + * Returns the font family list. + */ CRFontFamily * cr_font_family_prepend (CRFontFamily * a_this, CRFontFamily * a_family_to_prepend) @@ -247,6 +286,12 @@ cr_font_family_prepend (CRFontFamily * a_this, return a_family_to_prepend; } +/** + * cr_font_family_destroy: + * @a_this: the current instance of #CRFontFamily. + * + * Returns CR_OK upon sucessful completion, an error code otherwise. + */ enum CRStatus cr_font_family_destroy (CRFontFamily * a_this) { @@ -279,6 +324,11 @@ cr_font_family_destroy (CRFontFamily * a_this) *'font-size' manipulation functions definitions ***************************************************/ +/** + * cr_font_size_new: + * + * Returns the newly created font size. + */ CRFontSize * cr_font_size_new (void) { @@ -292,6 +342,12 @@ cr_font_size_new (void) return result; } +/** + * cr_font_size_clear: + * @a_this: the current instance of #CRFontSize + * + * Returns CR_OK upon successful completion, an error code otherwise. + */ enum CRStatus cr_font_size_clear (CRFontSize * a_this) { @@ -315,8 +371,15 @@ cr_font_size_clear (CRFontSize * a_this) return CR_OK; } +/** + * cr_font_size_copy: + * @a_dst: the destination #CRFontSize (where to copy to). + * @a_src: the source #CRFontSize (where to copy from). + * + * Returns CR_OK upon successful completion, an error code otherwise. + */ enum CRStatus -cr_font_size_copy (CRFontSize * a_dst, CRFontSize * a_src) +cr_font_size_copy (CRFontSize * a_dst, CRFontSize const * a_src) { g_return_val_if_fail (a_dst && a_src, CR_BAD_PARAM_ERROR); @@ -341,6 +404,13 @@ cr_font_size_copy (CRFontSize * a_dst, CRFontSize * a_src) return CR_OK; } +/** + * cr_font_size_set_predefined_absolute_font_size: + * @a_this: the current instance of #CRFontSize. + * @a_predefined: what to set. + * + * Returns CR_OK upon sucessful completion, an error code otherwise. + */ enum CRStatus cr_font_size_set_predefined_absolute_font_size (CRFontSize *a_this, enum CRPredefinedAbsoluteFontSize a_predefined) @@ -355,6 +425,13 @@ cr_font_size_set_predefined_absolute_font_size (CRFontSize *a_this, return CR_OK ; } +/** + * cr_font_size_set_relative_font_size: + * @a_this: the current instance of #CRFontSize + * @a_relative: the new relative font size + * + * Returns CR_OK upon successful completion, an error code otherwise. + */ enum CRStatus cr_font_size_set_relative_font_size (CRFontSize *a_this, enum CRRelativeFontSize a_relative) @@ -368,6 +445,14 @@ cr_font_size_set_relative_font_size (CRFontSize *a_this, return CR_OK ; } +/** + * cr_font_size_set_absolute_font_size: + * @a_this: the current instance of #CRFontSize + * @a_num_type: the type of number to set. + * @a_value: the actual value to set. + * + * Returns CR_OK upon succesful completion, an error code otherwise. + */ enum CRStatus cr_font_size_set_absolute_font_size (CRFontSize *a_this, enum CRNumType a_num_type, @@ -383,6 +468,12 @@ cr_font_size_set_absolute_font_size (CRFontSize *a_this, return CR_OK ; } +/** + * cr_font_size_set_to_inherit: + * @a_this: the current instance of #CRFontSize + * + * Returns CR_OK upon succesful completion, an error code otherwise. + */ enum CRStatus cr_font_size_set_to_inherit (CRFontSize *a_this) { @@ -394,16 +485,29 @@ cr_font_size_set_to_inherit (CRFontSize *a_this) return CR_OK ; } +/** + * cr_font_size_is_set_to_inherit: + * @a_this: the current instance of #CRFontSize. + * + * Returns TRUE if the current instance is set to 'inherit'. + */ gboolean -cr_font_size_is_set_to_inherit (CRFontSize *a_this) +cr_font_size_is_set_to_inherit (CRFontSize const *a_this) { g_return_val_if_fail (a_this, FALSE) ; return a_this->type == INHERITED_FONT_SIZE ; } +/** + * cr_font_size_to_string: + * @a_this: the current instance of #CRFontSize + * + * Returns the serialized form of #CRFontSize. The returned string + * has to bee freed using g_free(). + */ gchar * -cr_font_size_to_string (CRFontSize * a_this) +cr_font_size_to_string (CRFontSize const * a_this) { gchar *str = NULL; @@ -433,9 +537,15 @@ cr_font_size_to_string (CRFontSize * a_this) return str; } +/** + * cr_font_size_get_smaller_predefined: + * @a_font_size: the font size to consider. + * @a_smaller_size: out parameter. The a smaller value than @a_font_size. + */ void -cr_font_size_get_smaller_predefined_font_size (enum CRPredefinedAbsoluteFontSize a_font_size, - enum CRPredefinedAbsoluteFontSize *a_smaller_size) +cr_font_size_get_smaller_predefined_font_size + (enum CRPredefinedAbsoluteFontSize a_font_size, + enum CRPredefinedAbsoluteFontSize *a_smaller_size) { enum CRPredefinedAbsoluteFontSize result = FONT_SIZE_MEDIUM ; @@ -477,9 +587,17 @@ cr_font_size_get_smaller_predefined_font_size (enum CRPredefinedAbsoluteFontSize } +/** + * cr_font_size_get_larger_predefined_font_size: + * @a_font_size: the font size to consider. + * @a_larger_size: out parameter. the font size considered larger than + * @a_font_size. + * + */ void -cr_font_size_get_larger_predefined_font_size (enum CRPredefinedAbsoluteFontSize a_font_size, - enum CRPredefinedAbsoluteFontSize *a_larger_size) +cr_font_size_get_larger_predefined_font_size + (enum CRPredefinedAbsoluteFontSize a_font_size, + enum CRPredefinedAbsoluteFontSize *a_larger_size) { enum CRPredefinedAbsoluteFontSize result = FONT_SIZE_MEDIUM ; @@ -520,8 +638,16 @@ cr_font_size_get_larger_predefined_font_size (enum CRPredefinedAbsoluteFontSize *a_larger_size = result ; } +/** + * cr_font_size_is_predefined_absolute_font_size: + * @a_font_size: the font size to consider. + * + * Returns TRUE if the instance is an predefined absolute font size, FALSE + * otherwise. + */ gboolean -cr_font_size_is_predefined_absolute_font_size (enum CRPredefinedAbsoluteFontSize a_font_size) +cr_font_size_is_predefined_absolute_font_size + (enum CRPredefinedAbsoluteFontSize a_font_size) { if ((unsigned)a_font_size < NB_PREDEFINED_ABSOLUTE_FONT_SIZES) { return TRUE ; @@ -530,8 +656,14 @@ cr_font_size_is_predefined_absolute_font_size (enum CRPredefinedAbsoluteFontSize } } +/** + * cr_font_size_adjust_to_string: + * @a_this: the instance of #CRFontSizeAdjust. + * + * Returns the serialized form of #CRFontSizeAdjust + */ gchar * -cr_font_size_adjust_to_string (CRFontSizeAdjust * a_this) +cr_font_size_adjust_to_string (CRFontSizeAdjust const * a_this) { gchar *str = NULL; @@ -549,7 +681,7 @@ cr_font_size_adjust_to_string (CRFontSizeAdjust * a_this) if (a_this->num) str = (gchar *)cr_num_to_string (a_this->num); else - str = g_strdup ("unknow font-size-adjust property value"); // Should raise an error no? + str = g_strdup ("unknow font-size-adjust property value"); /* Should raise an error no?*/ break; case FONT_SIZE_ADJUST_INHERIT: str = g_strdup ("inherit"); @@ -557,6 +689,13 @@ cr_font_size_adjust_to_string (CRFontSizeAdjust * a_this) return str; } +/** + * cr_font_style_to_string: + * @a_code: the current instance of #CRFontStyle . + * + * Returns the serialized #CRFontStyle. The caller must free the returned + * string using g_free(). + */ const gchar * cr_font_style_to_string (enum CRFontStyle a_code) { @@ -582,6 +721,13 @@ cr_font_style_to_string (enum CRFontStyle a_code) return str; } +/** + * cr_font_variant_to_string: + * @a_code: the current instance of #CRFontVariant. + * + * Returns the serialized form of #CRFontVariant. The caller has + * to free the returned string using g_free(). + */ const gchar * cr_font_variant_to_string (enum CRFontVariant a_code) { @@ -601,10 +747,19 @@ cr_font_variant_to_string (enum CRFontVariant a_code) return str; } +/** + * cr_font_weight_get_bolder: + * @a_weight: the #CRFontWeight to consider. + * + * Returns a font weight bolder than @a_weight + */ enum CRFontWeight cr_font_weight_get_bolder (enum CRFontWeight a_weight) { - if (a_weight >= NB_FONT_WEIGHTS) { + if (a_weight == FONT_WEIGHT_INHERIT) { + cr_utils_trace_info ("can't return a bolder weight for FONT_WEIGHT_INHERIT") ; + return a_weight; + } else if (a_weight >= FONT_WEIGHT_900) { return FONT_WEIGHT_900 ; } else if (a_weight < FONT_WEIGHT_NORMAL) { return FONT_WEIGHT_NORMAL ; @@ -617,6 +772,12 @@ cr_font_weight_get_bolder (enum CRFontWeight a_weight) } } +/** + * cr_font_weight_to_string: + * @a_code: the font weight to consider. + * + * Returns the serialized form of #CRFontWeight. + */ const gchar * cr_font_weight_to_string (enum CRFontWeight a_code) { @@ -672,6 +833,12 @@ cr_font_weight_to_string (enum CRFontWeight a_code) return str; } +/** + * cr_font_stretch_to_string: + * @a_code: the instance of #CRFontStretch to consider. + * + * Returns the serialized form of #CRFontStretch. + */ const gchar * cr_font_stretch_to_string (enum CRFontStretch a_code) { @@ -718,6 +885,11 @@ cr_font_stretch_to_string (enum CRFontStretch a_code) return str; } +/** + * cr_font_size_destroy: + * @a_font_size: the font size to destroy + * + */ void cr_font_size_destroy (CRFontSize * a_font_size) { @@ -730,6 +902,11 @@ cr_font_size_destroy (CRFontSize * a_font_size) *'font-size-adjust' manipulation function definition *******************************************************/ +/** + * cr_font_size_adjust_new: + * + * Returns a newly built instance of #CRFontSizeAdjust + */ CRFontSizeAdjust * cr_font_size_adjust_new (void) { @@ -744,6 +921,11 @@ cr_font_size_adjust_new (void) return result; } +/** + * cr_font_size_adjust_destroy: + * @a_this: the current instance of #CRFontSizeAdjust. + * + */ void cr_font_size_adjust_destroy (CRFontSizeAdjust * a_this) { diff --git a/src/libcroco/cr-fonts.h b/src/libcroco/cr-fonts.h index 45446180b..9eaeeeb98 100644 --- a/src/libcroco/cr-fonts.h +++ b/src/libcroco/cr-fonts.h @@ -25,7 +25,6 @@ #ifndef __CR_FONTS_H__ #define __CR_FONTS_H__ -#endif #include "cr-utils.h" #include "cr-num.h" @@ -236,7 +235,7 @@ cr_font_family_append (CRFontFamily *a_this, CRFontFamily *a_family_to_append) ; guchar * -cr_font_family_to_string (CRFontFamily *a_this, +cr_font_family_to_string (CRFontFamily const *a_this, gboolean a_walk_font_family_list) ; CRFontFamily * @@ -259,7 +258,7 @@ CRFontSize * cr_font_size_new (void) ; enum CRStatus cr_font_size_clear (CRFontSize *a_this) ; enum CRStatus cr_font_size_copy (CRFontSize *a_dst, - CRFontSize *a_src) ; + CRFontSize const *a_src) ; enum CRStatus cr_font_size_set_predefined_absolute_font_size (CRFontSize *a_this, enum CRPredefinedAbsoluteFontSize a_predefined) ; enum CRStatus cr_font_size_set_relative_font_size (CRFontSize *a_this, @@ -271,9 +270,9 @@ enum CRStatus cr_font_size_set_absolute_font_size (CRFontSize *a_this, enum CRStatus cr_font_size_set_to_inherit (CRFontSize *a_this) ; -gboolean cr_font_size_is_set_to_inherit (CRFontSize *a_this) ; +gboolean cr_font_size_is_set_to_inherit (CRFontSize const *a_this) ; -gchar* cr_font_size_to_string (CRFontSize *a_this) ; +gchar* cr_font_size_to_string (CRFontSize const *a_this) ; void cr_font_size_destroy (CRFontSize *a_font_size) ; @@ -283,7 +282,7 @@ void cr_font_size_destroy (CRFontSize *a_font_size) ; CRFontSizeAdjust * cr_font_size_adjust_new (void) ; -gchar * cr_font_size_adjust_to_string (CRFontSizeAdjust *a_this) ; +gchar * cr_font_size_adjust_to_string (CRFontSizeAdjust const *a_this) ; void cr_font_size_adjust_destroy (CRFontSizeAdjust *a_this) ; @@ -312,3 +311,5 @@ const gchar * cr_font_variant_to_string (enum CRFontVariant a_code) ; const gchar * cr_font_stretch_to_string (enum CRFontStretch a_code) ; G_END_DECLS + +#endif diff --git a/src/libcroco/cr-input.c b/src/libcroco/cr-input.c index 861329227..33321d9f7 100644 --- a/src/libcroco/cr-input.c +++ b/src/libcroco/cr-input.c @@ -27,7 +27,8 @@ #include "cr-enc-handler.h" /** - *@file + *@CRInput: + * *The definition of the #CRInput class. */ @@ -110,15 +111,17 @@ cr_input_new_real (void) ***************/ /** - *Creates a new input stream from a memory buffer. - *@param a_buf the memory buffer to create the input stream from. + * cr_input_new_from_buf: + *@a_buf: the memory buffer to create the input stream from. *The #CRInput keeps this pointer so user should not free it !. - *@param a_len the size of the input buffer. - *@param a_enc the buffer's encoding. - *@param a_free_buf if set to TRUE, this a_buf will be freed + *@a_len: the size of the input buffer. + *@a_enc: the buffer's encoding. + *@a_free_buf: if set to TRUE, this a_buf will be freed *at the destruction of this instance. If set to false, it is up *to the caller to free it. - *@return the newly built instance of #CRInput. + * + *Creates a new input stream from a memory buffer. + *Returns the newly built instance of #CRInput. */ CRInput * cr_input_new_from_buf (guchar * a_buf, @@ -175,13 +178,14 @@ cr_input_new_from_buf (guchar * a_buf, } /** + * cr_input_new_from_uri: + *@a_file_uri: the file to create *the input stream from. + *@a_enc: the encoding of the file *to create the input from. + * *Creates a new input stream from *a file. - *@param a_file_uri the file to create - *the input stream from. - *@param a_enc the encoding of the file - *to create the input from - *@return the newly created input stream if + * + *Returns the newly created input stream if *this method could read the file and create it, *NULL otherwise. */ @@ -268,8 +272,10 @@ cr_input_new_from_uri (const gchar * a_file_uri, enum CREncoding a_enc) } /** + * cr_input_destroy: + *@a_this: the current instance of #CRInput. + * *The destructor of the #CRInput class. - *@param a_this the current instance of #CRInput. */ void cr_input_destroy (CRInput * a_this) @@ -291,9 +297,11 @@ cr_input_destroy (CRInput * a_this) } /** + * cr_input_ref: + *@a_this: the current instance of #CRInput. + * *Increments the reference count of the current *instance of #CRInput. - *@param a_this the current instance of #CRInput. */ void cr_input_ref (CRInput * a_this) @@ -304,11 +312,14 @@ cr_input_ref (CRInput * a_this) } /** + * cr_input_unref: + *@a_this: the current instance of #CRInput. + * *Decrements the reference count of this instance *of #CRInput. If the reference count goes down to *zero, this instance is destroyed. - *@param a_this the current instance of #CRInput. * + * Returns TRUE if the instance of #CRInput got destroyed, false otherwise. */ gboolean cr_input_unref (CRInput * a_this) @@ -327,18 +338,21 @@ cr_input_unref (CRInput * a_this) } /** - *Tests wether the current instance of - *#CRInput has reached its input buffer. - *@param a_this the current instance of #CRInput. - *@param a_end_of_input out parameter. Is set to TRUE if + * cr_input_end_of_input: + *@a_this: the current instance of #CRInput. + *@a_end_of_input: out parameter. Is set to TRUE if *the current instance has reached the end of its input buffer, *FALSE otherwise. - *@param CR_OK upon successful completion, an error code otherwise. - *Note that all the out parameters of this method are valid if - *and only if this method returns CR_OK. + * + *Tests wether the current instance of + *#CRInput has reached its input buffer. + * + * Returns CR_OK upon successful completion, an error code otherwise. + * Note that all the out parameters of this method are valid if + * and only if this method returns CR_OK. */ enum CRStatus -cr_input_end_of_input (CRInput * a_this, gboolean * a_end_of_input) +cr_input_end_of_input (CRInput const * a_this, gboolean * a_end_of_input) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_end_of_input, CR_BAD_PARAM_ERROR); @@ -350,13 +364,14 @@ cr_input_end_of_input (CRInput * a_this, gboolean * a_end_of_input) } /** + * cr_input_get_nb_bytes_left: + *@a_this: the current instance of #CRInput. + * *Returns the number of bytes left in the input stream - *before the end. - *@param a_this the current instance of #CRInput. - *@return the number of characters left or -1 in case of error. + *before the end, -1 in case of error. */ glong -cr_input_get_nb_bytes_left (CRInput * a_this) +cr_input_get_nb_bytes_left (CRInput const * a_this) { g_return_val_if_fail (a_this && PRIVATE (a_this), -1); g_return_val_if_fail (PRIVATE (a_this)->nb_bytes @@ -371,14 +386,16 @@ cr_input_get_nb_bytes_left (CRInput * a_this) } /** - *Returns the next byte of the input. - *Update the state of the input so that + * cr_input_read_byte: + *@a_this: the current instance of #CRInput. + *@a_byte: out parameter the returned byte. + * + *Gets the next byte of the input. + *Updates the state of the input so that *the next invocation of this method returns *the next coming byte. * - *@param a_this the current instance of #CRInput. - *@param a_byte out parameter the returned byte. - *@return CR_OK upon successful completion, an error code + *Returns CR_OK upon successful completion, an error code *otherwise. All the out parameters of this method are valid if *and only if this method returns CR_OK. */ @@ -407,11 +424,14 @@ cr_input_read_byte (CRInput * a_this, guchar * a_byte) } /** + * cr_input_read_char: + *@a_this: the current instance of CRInput. + *@a_char: out parameter. The read character. + * *Reads an unicode character from the current instance of *#CRInput. - *@param a_this the current instance of CRInput. - *@param a_char out parameter. The read character. - *@return CR_OK upon successful completion, an error code + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus @@ -462,11 +482,13 @@ cr_input_read_char (CRInput * a_this, guint32 * a_char) } /** + * cr_input_set_line_num: + *@a_this: the "this pointer" of the current instance of #CRInput. + *@a_line_num: the new line number. + * *Setter of the current line number. - *@param a_this the "this pointer" of the current instance of - *#CRInput. - *@param a_line_num the new line number. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Return CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_set_line_num (CRInput * a_this, glong a_line_num) @@ -479,14 +501,16 @@ cr_input_set_line_num (CRInput * a_this, glong a_line_num) } /** + * cr_input_get_line_num: + *@a_this: the "this pointer" of the current instance of #CRInput. + *@a_line_num: the returned line number. + * *Getter of the current line number. - *@param a_this the "this pointer" of the current instance of - *#CRInput. - *@param a_line_num the returned line number. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_input_get_line_num (CRInput * a_this, glong * a_line_num) +cr_input_get_line_num (CRInput const * a_this, glong * a_line_num) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_line_num, CR_BAD_PARAM_ERROR); @@ -497,11 +521,13 @@ cr_input_get_line_num (CRInput * a_this, glong * a_line_num) } /** + * cr_input_set_column_num: + *@a_this: the "this pointer" of the current instance of #CRInput. + *@a_col: the new column number. + * *Setter of the current column number. - *@param a_this the "this pointer" of the current instance of - *#CRInput. - *@param a_col the new column number. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_set_column_num (CRInput * a_this, glong a_col) @@ -514,14 +540,16 @@ cr_input_set_column_num (CRInput * a_this, glong a_col) } /** + * cr_input_get_column_num: + *@a_this: the "this pointer" of the current instance of #CRInput. + *@a_col: out parameter + * *Getter of the current column number. - *@param a_this the "this pointer" of the current instance of - *#CRInput. - *@param a_col out parameter - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_input_get_column_num (CRInput * a_this, glong * a_col) +cr_input_get_column_num (CRInput const * a_this, glong * a_col) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_col, CR_BAD_PARAM_ERROR); @@ -532,10 +560,13 @@ cr_input_get_column_num (CRInput * a_this, glong * a_col) } /** + * cr_input_increment_line_num: + *@a_this: the "this pointer" of the current instance of #CRInput. + *@a_increment: the increment to add to the line number. + * *Increments the current line number. - *@param a_this the "this pointer" of the current instance of - *#CRInput. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_increment_line_num (CRInput * a_this, glong a_increment) @@ -548,10 +579,13 @@ cr_input_increment_line_num (CRInput * a_this, glong a_increment) } /** + * cr_input_increment_col_num: + *@a_this: the "this pointer" of the current instance of #CRInput. + *@a_increment: the increment to add to the column number. + * *Increments the current column number. - *@param a_this the "this pointer" of the current instance of - *#CRInput. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_increment_col_num (CRInput * a_this, glong a_increment) @@ -564,13 +598,15 @@ cr_input_increment_col_num (CRInput * a_this, glong a_increment) } /** + * cr_input_consume_char: + *@a_this: the this pointer. + *@a_char: the character to consume. If set to zero, + *consumes any character. + * *Consumes the next character of the input stream if *and only if that character equals a_char. * - *@param a_this the this pointer. - *@param a_char the character to consume. If set to zero, - *consumes any character. - *@return CR_OK upon successful completion, CR_PARSING_ERROR if + *Returns CR_OK upon successful completion, CR_PARSING_ERROR if *next char is different from a_char, an other error code otherwise */ enum CRStatus @@ -595,21 +631,23 @@ cr_input_consume_char (CRInput * a_this, guint32 a_char) } /** + * cr_input_consume_chars: + *@a_this: the this pointer of the current instance of #CRInput. + *@a_char: the character to consume. + *@a_nb_char: in/out parameter. The number of characters to consume. + *If set to a negative value, the function will consume all the occurences + *of a_char found. + *After return, if the return value equals CR_OK, this variable contains + *the number of characters actually consumed. + * *Consumes up to a_nb_char occurences of the next contiguous characters *which equal a_char. Note that the next character of the input stream **MUST* equal a_char to trigger the consumption, or else, the error *code CR_PARSING_ERROR is returned. *If the number of contiguous characters that equals a_char is less than *a_nb_char, then this function consumes all the characters it can consume. - * - *@param a_this the this pointer of the current instance of #CRInput. - *@param a_char the character to consume. - *@param a_nb_char in/out parameter. The number of characters to consume. - *If set to a negative value, the function will consume all the occurences - *of a_char found. - *After return, if the return value equals CR_OK, this variable contains - *the number of characters actually consumed. - *@return CR_OK if at least one character has been consumed, an error code + * + *Returns CR_OK if at least one character has been consumed, an error code *otherwise. */ enum CRStatus @@ -643,13 +681,15 @@ cr_input_consume_chars (CRInput * a_this, guint32 a_char, gulong * a_nb_char) } /** + * cr_input_consume_white_spaces: + *@a_this: the "this pointer" of the current instance of #CRInput. + *@a_nb_chars: in/out parameter. The number of white spaces to + *consume. After return, holds the number of white spaces actually consumed. + * *Same as cr_input_consume_chars() but this one consumes white *spaces. * - *@param a_this the "this pointer" of the current instance of #CRInput. - *@param a_nb_chars in/out parameter. The number of white spaces to - *consume. After return, holds the number of white spaces actually consumed. - *@return CR_OK upon successful completion, an error code otherwise. + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_consume_white_spaces (CRInput * a_this, gulong * a_nb_chars) @@ -688,17 +728,20 @@ cr_input_consume_white_spaces (CRInput * a_this, gulong * a_nb_chars) } /** + * cr_input_peek_char: + *@a_this: the current instance of #CRInput. + *@a_char: out parameter. The returned character. + * *Same as cr_input_read_char() but does not update the *internal state of the input stream. The next call *to cr_input_peek_char() or cr_input_read_char() will thus *return the same character as the current one. - *@param a_this the current instance of #CRInput. - *@param a_char out parameter. The returned character. - *@return CR_OK upon successful completion, an error code + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus -cr_input_peek_char (CRInput * a_this, guint32 * a_char) +cr_input_peek_char (CRInput const * a_this, guint32 * a_char) { enum CRStatus status = CR_OK; glong consumed = 0, @@ -727,6 +770,14 @@ cr_input_peek_char (CRInput * a_this, guint32 * a_char) } /** + * cr_input_peek_byte: + *@a_this: the current instance of #CRInput. + *@a_origin: the origin to consider in the calculation + *of the position of the byte to peek. + *@a_offset: the offset of the byte to peek, starting from + *the origin specified by a_origin. + *@a_byte: out parameter the peeked byte. + * *Gets a byte from the input stream, *starting from the current position in the input stream. *Unlike cr_input_peek_next_byte() this method @@ -734,21 +785,12 @@ cr_input_peek_char (CRInput * a_this, guint32 * a_char) *Subsequent calls to cr_input_peek_byte with the same arguments *will return the same byte. * - *@param a_this the current instance of #CRInput. - *@param a_origin the origin to consider in the calculation - *of the position of the byte to peek. - *@param a_offset the offset of the byte to peek, starting from - *the origin specified by a_origin. - *@param a_byte out parameter the peeked byte. - *@return CR_OK upon successful completion or, - * - *<ul> - *<li>CR_BAD_PARAM_ERROR if at least one of the parameters is invalid</li> - *<li>CR_OUT_OF_BOUNDS_ERROR if the indexed byte is out of bounds</li> - *</ul> + *Returns CR_OK upon successful completion or, + *CR_BAD_PARAM_ERROR if at least one of the parameters is invalid; + *CR_OUT_OF_BOUNDS_ERROR if the indexed byte is out of bounds. */ enum CRStatus -cr_input_peek_byte (CRInput * a_this, enum CRSeekPos a_origin, +cr_input_peek_byte (CRInput const * a_this, enum CRSeekPos a_origin, gulong a_offset, guchar * a_byte) { gulong abs_offset = 0; @@ -786,18 +828,21 @@ cr_input_peek_byte (CRInput * a_this, enum CRSeekPos a_origin, } /** - *Same as cr_input_peek_byte() but with a simplified - *interface. - *@param a_this the current byte input stream. - *@param a_offset the offset of the byte to peek, starting + * cr_input_peek_byte2: + *@a_this: the current byte input stream. + *@a_offset: the offset of the byte to peek, starting *from the current input position pointer. - *@param a_eof out parameter. Is set to true is we reach end of + *@a_eof: out parameter. Is set to true is we reach end of *stream. If set to NULL by the caller, this parameter is not taken *in account. - *@return the read byte or 0 if something bad happened. + * + *Same as cr_input_peek_byte() but with a simplified + *interface. + * + *Returns the read byte or 0 if something bad happened. */ guchar -cr_input_peek_byte2 (CRInput * a_this, gulong a_offset, gboolean * a_eof) +cr_input_peek_byte2 (CRInput const * a_this, gulong a_offset, gboolean * a_eof) { guchar result = 0; enum CRStatus status = CR_ERROR; @@ -817,12 +862,15 @@ cr_input_peek_byte2 (CRInput * a_this, gulong a_offset, gboolean * a_eof) } /** - *Returns the memory address of the byte located at a given offset - *in the input stream. - *@param a_this the current instance of #CRInput. - *@param a_offset the offset of the byte in the input stream starting + * cr_input_get_byte_addr: + *@a_this: the current instance of #CRInput. + *@a_offset: the offset of the byte in the input stream starting *from the beginning of the stream. - *@return the address, otherwise NULL if an error occured. + * + *Gets the memory address of the byte located at a given offset + *in the input stream. + * + *Returns the address, otherwise NULL if an error occured. */ guchar * cr_input_get_byte_addr (CRInput * a_this, gulong a_offset) @@ -837,10 +885,13 @@ cr_input_get_byte_addr (CRInput * a_this, gulong a_offset) } /** - *Returns the address of the current character pointer. - *@param a_this the current input stream - *@param a_offset out parameter. The returned address. - *@return CR_OK upon successful completion, an error code otherwise. + * cr_input_get_cur_byte_addr: + *@a_this: the current input stream + *@a_offset: out parameter. The returned address. + * + *Gets the address of the current character pointer. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_get_cur_byte_addr (CRInput * a_this, guchar ** a_offset) @@ -859,23 +910,20 @@ cr_input_get_cur_byte_addr (CRInput * a_this, guchar ** a_offset) } /** + * cr_input_seek_index: + *@a_this: the current instance of #CRInput. + *@a_origin: the origin to consider during the calculation + *of the absolute position of the new "current byte index". + *@a_pos: the relative offset of the new "current byte index." + *This offset is relative to the origin a_origin. + * *Sets the "current byte index" of the current instance *of #CRInput. Next call to cr_input_get_byte() will return *the byte next after the new "current byte index". * - *@param a_this the current instance of #CRInput. - * - *@param a_origin the origin to consider during the calculation - *of the absolute position of the new "current byte index". - * - *@param a_pos the relative offset of the new "current byte index." - *This offset is relative to the origin a_origin. - * - *@return CR_OK upon successful completion otherwise returns - *<ul> - *<li>CR_BAD_PARAM_ERROR if at least one of the parameters is not valid</li> - *<li>CR_OUT_BOUNDS_ERROR</li> - *</ul> + *Returns CR_OK upon successful completion otherwise returns + *CR_BAD_PARAM_ERROR if at least one of the parameters is not valid + *or CR_OUT_BOUNDS_ERROR in case of error. */ enum CRStatus cr_input_seek_index (CRInput * a_this, enum CRSeekPos a_origin, gint a_pos) @@ -916,26 +964,24 @@ cr_input_seek_index (CRInput * a_this, enum CRSeekPos a_origin, gint a_pos) } /** + * cr_input_get_cur_pos: + *@a_this: the current instance of #CRInput. + *@a_pos: out parameter. The returned position. + * *Gets the position of the "current byte index" which *is basically the position of the last returned byte in the *input stream. * - *@param a_this the current instance of #CRInput. - * - *@param a_pos out parameter. The returned position. - * - *@return CR_OK upon successful completion. Otherwise, - *<ul> - *<li>CR_BAD_PARAMETER_ERROR if at least one of the arguments is invalid.</li> - *<li>CR_START_OF_INPUT if no call to either cr_input_read_byte() + *Returns CR_OK upon successful completion. Otherwise, + *CR_BAD_PARAMETER_ERROR if at least one of the arguments is invalid. + *CR_START_OF_INPUT if no call to either cr_input_read_byte() *or cr_input_seek_index() have been issued before calling - *cr_input_get_cur_pos()</li> - *</ul> + *cr_input_get_cur_pos() *Note that the out parameters of this function are valid if and only if this *function returns CR_OK. */ enum CRStatus -cr_input_get_cur_pos (CRInput * a_this, CRInputPos * a_pos) +cr_input_get_cur_pos (CRInput const * a_this, CRInputPos * a_pos) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_pos, CR_BAD_PARAM_ERROR); @@ -950,17 +996,20 @@ cr_input_get_cur_pos (CRInput * a_this, CRInputPos * a_pos) } /** + * cr_input_get_parsing_location: + *@a_this: the current instance of #CRInput + *@a_loc: the set parsing location. + * *Gets the current parsing location. *The Parsing location is a public datastructure that *represents the current line/column/byte offset/ in the input *stream. - *@param a_this the current instance of #CRInput - *@param a_loc the set parsing location. - *@return CR_OK upon successful completion, an error + * + *Returns CR_OK upon successful completion, an error *code otherwise. */ enum CRStatus -cr_input_get_parsing_location (CRInput *a_this, +cr_input_get_parsing_location (CRInput const *a_this, CRParsingLocation *a_loc) { g_return_val_if_fail (a_this @@ -979,17 +1028,20 @@ cr_input_get_parsing_location (CRInput *a_this, } /** + * cr_input_get_cur_index: + *@a_this: the "this pointer" of the current instance of + *#CRInput + *@a_index: out parameter. The returned index. + * *Getter of the next byte index. *It actually returns the index of the *next byte to be read. - *@param a_this the "this pointer" of the current instance of - *#CRInput - *@param a_index out parameter. The returned index. - *@return CR_OK upon successful completion, an error code + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus -cr_input_get_cur_index (CRInput * a_this, glong * a_index) +cr_input_get_cur_index (CRInput const * a_this, glong * a_index) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_index, CR_BAD_PARAM_ERROR); @@ -1000,12 +1052,15 @@ cr_input_get_cur_index (CRInput * a_this, glong * a_index) } /** + * cr_input_set_cur_index: + *@a_this: the "this pointer" of the current instance + *of #CRInput . + *@a_index: the new index to set. + * *Setter of the next byte index. *It sets the index of the next byte to be read. - *@param a_this the "this pointer" of the current instance - *of #CRInput . - *@param a_index the new index to set. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_set_cur_index (CRInput * a_this, glong a_index) @@ -1018,10 +1073,13 @@ cr_input_set_cur_index (CRInput * a_this, glong a_index) } /** + * cr_input_set_end_of_file: + *@a_this: the current instance of #CRInput. + *@a_eof: the new end of file flag. + * *Sets the end of file flag. - *@param a_this the current instance of #CRInput. - *@param a_eof the new end of file flag. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_input_set_end_of_file (CRInput * a_this, gboolean a_eof) @@ -1034,14 +1092,17 @@ cr_input_set_end_of_file (CRInput * a_this, gboolean a_eof) } /** - *Gets the end of file flag. - *@param a_this the current instance of #CRInput. - *@param a_eof out parameter the place to put the end of + * cr_input_get_end_of_file: + *@a_this: the current instance of #CRInput. + *@a_eof: out parameter the place to put the end of *file flag. - *@return CR_OK upon successful completion, an error code otherwise. + * + *Gets the end of file flag. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_input_get_end_of_file (CRInput * a_this, gboolean * a_eof) +cr_input_get_end_of_file (CRInput const * a_this, gboolean * a_eof) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_eof, CR_BAD_PARAM_ERROR); @@ -1052,10 +1113,13 @@ cr_input_get_end_of_file (CRInput * a_this, gboolean * a_eof) } /** + * cr_input_set_end_of_line: + *@a_this: the current instance of #CRInput. + *@a_eol: the new end of line flag. + * *Sets the end of line flag. - *@param a_this the current instance of #CRInput. - *@param a_eol the new end of line flag. - *@return CR_OK upon successful completion, an error code + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus @@ -1069,15 +1133,18 @@ cr_input_set_end_of_line (CRInput * a_this, gboolean a_eol) } /** - *Gets the end of line flag of the current input. - *@param a_this the current instance of #CRInput - *@param a_eol out parameter. The place to put + * cr_input_get_end_of_line: + *@a_this: the current instance of #CRInput + *@a_eol: out parameter. The place to put *the returned flag - *@return CR_OK upon successful completion, an error code + * + *Gets the end of line flag of the current input. + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus -cr_input_get_end_of_line (CRInput * a_this, gboolean * a_eol) +cr_input_get_end_of_line (CRInput const * a_this, gboolean * a_eol) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_eol, CR_BAD_PARAM_ERROR); @@ -1088,14 +1155,17 @@ cr_input_get_end_of_line (CRInput * a_this, gboolean * a_eol) } /** + * cr_input_set_cur_pos: + *@a_this: the "this pointer" of the current instance of + *#CRInput. + *@a_pos: the new position. + * *Sets the current position in the input stream. * - *@param a_this the "this pointer" of the current instance of - *#CRInput. - *@param a_pos the new position. + * Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_input_set_cur_pos (CRInput * a_this, CRInputPos * a_pos) +cr_input_set_cur_pos (CRInput * a_this, CRInputPos const * a_pos) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_pos, CR_BAD_PARAM_ERROR); diff --git a/src/libcroco/cr-input.h b/src/libcroco/cr-input.h index 976b73fb0..9eb402a87 100644 --- a/src/libcroco/cr-input.h +++ b/src/libcroco/cr-input.h @@ -93,15 +93,15 @@ enum CRStatus cr_input_consume_white_spaces (CRInput *a_this, gulong *a_nb_chars) ; enum CRStatus -cr_input_peek_byte (CRInput *a_this, enum CRSeekPos a_origin, +cr_input_peek_byte (CRInput const *a_this, enum CRSeekPos a_origin, gulong a_offset, guchar *a_byte) ; guchar -cr_input_peek_byte2 (CRInput *a_this, gulong a_offset, +cr_input_peek_byte2 (CRInput const *a_this, gulong a_offset, gboolean *a_eof) ; enum CRStatus -cr_input_peek_char (CRInput *a_this, guint32 *a_char) ; +cr_input_peek_char (CRInput const *a_this, guint32 *a_char) ; guchar * cr_input_get_byte_addr (CRInput *a_this, @@ -115,29 +115,29 @@ cr_input_seek_index (CRInput *a_this, enum CRSeekPos a_origin, gint a_pos) ; enum CRStatus -cr_input_get_cur_index (CRInput *a_this, glong *a_index) ; +cr_input_get_cur_index (CRInput const *a_this, glong *a_index) ; enum CRStatus cr_input_set_cur_index (CRInput *a_this, glong a_index) ; enum CRStatus -cr_input_get_cur_pos (CRInput *a_this, CRInputPos * a_pos) ; +cr_input_get_cur_pos (CRInput const *a_this, CRInputPos * a_pos) ; enum CRStatus -cr_input_set_cur_pos (CRInput *a_this, CRInputPos *a_pos) ; +cr_input_set_cur_pos (CRInput *a_this, CRInputPos const *a_pos) ; enum CRStatus -cr_input_get_parsing_location (CRInput *a_this, +cr_input_get_parsing_location (CRInput const *a_this, CRParsingLocation *a_loc) ; enum CRStatus -cr_input_get_end_of_line (CRInput *a_this, gboolean *a_eol) ; +cr_input_get_end_of_line (CRInput const *a_this, gboolean *a_eol) ; enum CRStatus cr_input_set_end_of_line (CRInput *a_this, gboolean a_eol) ; enum CRStatus -cr_input_get_end_of_file (CRInput *a_this, gboolean *a_eof) ; +cr_input_get_end_of_file (CRInput const *a_this, gboolean *a_eof) ; enum CRStatus cr_input_set_end_of_file (CRInput *a_this, gboolean a_eof) ; @@ -146,13 +146,13 @@ enum CRStatus cr_input_set_line_num (CRInput *a_this, glong a_line_num) ; enum CRStatus -cr_input_get_line_num (CRInput *a_this, glong *a_line_num) ; +cr_input_get_line_num (CRInput const *a_this, glong *a_line_num) ; enum CRStatus cr_input_set_column_num (CRInput *a_this, glong a_col) ; enum CRStatus -cr_input_get_column_num (CRInput *a_this, glong *a_col) ; +cr_input_get_column_num (CRInput const *a_this, glong *a_col) ; enum CRStatus cr_input_increment_line_num (CRInput *a_this, @@ -163,10 +163,10 @@ cr_input_increment_col_num (CRInput *a_this, glong a_increment) ; glong -cr_input_get_nb_bytes_left (CRInput *a_this) ; +cr_input_get_nb_bytes_left (CRInput const *a_this) ; enum CRStatus -cr_input_end_of_input (CRInput *a_this, gboolean *a_end_of_input) ; +cr_input_end_of_input (CRInput const *a_this, gboolean *a_end_of_input) ; G_END_DECLS diff --git a/src/libcroco/cr-num.c b/src/libcroco/cr-num.c index 062784c84..d3aab552b 100644 --- a/src/libcroco/cr-num.c +++ b/src/libcroco/cr-num.c @@ -23,7 +23,8 @@ */ /** - *@file + *@CRNum: + * *The definition *of the #CRNum class. */ @@ -32,9 +33,11 @@ #include "string.h" /** - *The default constructor of + * cr_num_new: + * *#CRNum. - *@return the newly built instance of + * + *Returns the newly built instance of *#CRNum. */ CRNum * @@ -53,16 +56,14 @@ cr_num_new (void) } /** - *A constructor of #CRNum. - *@param a_is_natural indicates whether the intance of #CRNum is - *a natural number or not. - *@param a_integer_part the integer part of the instance - *of #CRNum - *@param a_decimal_part in case the instance of #CRNum - *natural number (but a decimal one) this parameter - *is the decimal part of the instance of #CRNum. - *@return the newly built instance of #CRNum or - *NULL if an error arises. + * cr_num_new_with_val: + * @a_val: the numerical value of the number. + * @a_type: the type of number. + * + * A constructor of #CRNum. + * + * Returns the newly built instance of #CRNum or + * NULL if an error arises. */ CRNum * cr_num_new_with_val (gdouble a_val, enum CRNumType a_type) @@ -80,16 +81,16 @@ cr_num_new_with_val (gdouble a_val, enum CRNumType a_type) } /** - *Returns the string representation of the - *current instance of #CRNum. - *@param a_this the current instance of #CRNum. - *@return the newly built string representation + * cr_num_to_string: + *@a_this: the current instance of #CRNum. + * + *Returns the newly built string representation *of the current instance of #CRNum. The returned *string is NULL terminated. The caller *must* *free the returned string. */ guchar * -cr_num_to_string (CRNum * a_this) +cr_num_to_string (CRNum const * a_this) { guchar *tmp_char1 = NULL, *tmp_char2 = NULL, @@ -201,16 +202,19 @@ cr_num_to_string (CRNum * a_this) } /** - *Copies an instance of #CRNum. - *@param a_src the instance of #CRNum to copy. + * cr_num_copy: + *@a_src: the instance of #CRNum to copy. *Must be non NULL. - *@param a_dst the destination of the copy. + *@a_dest: the destination of the copy. *Must be non NULL - *@return CR_OK upon successful completion, an + * + *Copies an instance of #CRNum. + * + *Returns CR_OK upon successful completion, an *error code otherwise. */ enum CRStatus -cr_num_copy (CRNum * a_dest, CRNum * a_src) +cr_num_copy (CRNum * a_dest, CRNum const * a_src) { g_return_val_if_fail (a_dest && a_src, CR_BAD_PARAM_ERROR); @@ -220,13 +224,16 @@ cr_num_copy (CRNum * a_dest, CRNum * a_src) } /** + * cr_num_dup: + *@a_this: the instance of #CRNum to duplicate. + * *Duplicates an instance of #CRNum - *@param a_this the instance of #CRNum to duplicate. - *@return the newly created (duplicated) instance of #CRNum. + * + *Returns the newly created (duplicated) instance of #CRNum. *Must be freed by cr_num_destroy(). */ CRNum * -cr_num_dup (CRNum * a_this) +cr_num_dup (CRNum const * a_this) { CRNum *result = NULL; enum CRStatus status = CR_OK; @@ -243,11 +250,14 @@ cr_num_dup (CRNum * a_this) } /** + * cr_num_set: *Sets an instance of #CRNum. - *@param a_this the current instance of #CRNum to be set. - *@param a_val the new numerical value to be hold by the current + *@a_this: the current instance of #CRNum to be set. + *@a_val: the new numerical value to be hold by the current *instance of #CRNum - *@param a_type the new type of #CRNum. + *@a_type: the new type of #CRNum. + * + * Returns CR_OK upon succesful completion, an error code otherwise. */ enum CRStatus cr_num_set (CRNum * a_this, gdouble a_val, enum CRNumType a_type) @@ -261,15 +271,19 @@ cr_num_set (CRNum * a_this, gdouble a_val, enum CRNumType a_type) } /** + * cr_num_is_fixed_length: + * @a_this: the current instance of #CRNum . + * *Tests if the current instance of #CRNum is a fixed *length value or not. Typically a fixed length value *is anything from NUM_LENGTH_EM to NUM_LENGTH_PC. *See the definition of #CRNumType to see what we mean. - *@return TRUE if the instance of #CRNum is a fixed length number, + * + *Returns TRUE if the instance of #CRNum is a fixed length number, *FALSE otherwise. */ gboolean -cr_num_is_fixed_length (CRNum * a_this) +cr_num_is_fixed_length (CRNum const * a_this) { gboolean result = FALSE; @@ -283,9 +297,11 @@ cr_num_is_fixed_length (CRNum * a_this) } /** - *The destructor of #CRNum. - *@param a_this the this pointer of + * cr_num_destroy: + *@a_this: the this pointer of *the current instance of #CRNum. + * + *The destructor of #CRNum. */ void cr_num_destroy (CRNum * a_this) diff --git a/src/libcroco/cr-num.h b/src/libcroco/cr-num.h index 83e9dc7c6..2b73aaf79 100644 --- a/src/libcroco/cr-num.h +++ b/src/libcroco/cr-num.h @@ -102,20 +102,20 @@ cr_num_new_with_val (gdouble a_val, enum CRNumType a_type) ; CRNum * -cr_num_dup (CRNum *a_this) ; +cr_num_dup (CRNum const *a_this) ; guchar * -cr_num_to_string (CRNum *a_this) ; +cr_num_to_string (CRNum const *a_this) ; enum CRStatus -cr_num_copy (CRNum *a_dest, CRNum *a_src) ; +cr_num_copy (CRNum *a_dest, CRNum const *a_src) ; enum CRStatus cr_num_set (CRNum *a_this, gdouble a_val, enum CRNumType a_type) ; gboolean -cr_num_is_fixed_length (CRNum *a_this) ; +cr_num_is_fixed_length (CRNum const *a_this) ; void cr_num_destroy (CRNum *a_this) ; diff --git a/src/libcroco/cr-om-parser.c b/src/libcroco/cr-om-parser.c index c9ce032af..dd6cacc06 100644 --- a/src/libcroco/cr-om-parser.c +++ b/src/libcroco/cr-om-parser.c @@ -28,7 +28,8 @@ #define UNUSED(_param) ((void)(_param)) /** - *@file + *@CROMParser: + * *The definition of the CSS Object Model Parser. *This parser uses (and sits) the SAC api of libcroco defined *in cr-parser.h and cr-doc-handler.h @@ -773,9 +774,11 @@ unrecoverable_error (CRDocHandler * a_this) ********************************************/ /** + * cr_om_parser_new: + *@a_input: the input stream. + * *Constructor of the CROMParser. - *@param a_input the input stream. - *@return the newly built instance of #CROMParser. + *Returns the newly built instance of #CROMParser. */ CROMParser * cr_om_parser_new (CRInput * a_input) @@ -824,13 +827,16 @@ cr_om_parser_new (CRInput * a_input) } /** + * cr_om_parser_parse_buf: + *@a_this: the current instance of #CROMParser. + *@a_buf: the in memory buffer to parse. + *@a_len: the length of the in memory buffer in number of bytes. + *@a_enc: the encoding of the in memory buffer. + *@a_result: out parameter the resulting style sheet + * *Parses the content of an in memory buffer. - *@param a_this the current instance of #CROMParser. - *@param a_buf the in memory buffer to parse. - *@param a_len the length of the in memory buffer in number of bytes. - *@param a_enc the encoding of the in memory buffer. - *@param a_result out parameter the resulting style sheet - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_om_parser_parse_buf (CROMParser * a_this, @@ -871,12 +877,15 @@ cr_om_parser_parse_buf (CROMParser * a_this, } /** + * cr_om_parser_simply_parse_buf: + *@a_buf: the css2 in memory buffer. + *@a_len: the length of the in memory buffer. + *@a_enc: the encoding of the in memory buffer. + *@a_result: out parameter. The resulting css2 style sheet. + * *The simpler way to parse an in memory css2 buffer. - *@param a_buf the css2 in memory buffer. - *@param a_len the length of the in memory buffer. - *@param a_enc the encoding of the in memory buffer. - *@param a_result out parameter. The resulting css2 style sheet. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_om_parser_simply_parse_buf (const guchar * a_buf, @@ -906,16 +915,18 @@ cr_om_parser_simply_parse_buf (const guchar * a_buf, } /** - *Parses a css2 stylesheet contained - *in a file. - *@param a_this the current instance of the cssom parser. - *@param a_file_uri the uri of the file. + * cr_om_parser_parse_file: + *@a_this: the current instance of the cssom parser. + *@a_file_uri: the uri of the file. *(only local file paths are suppported so far) - *@param a_enc the encoding of the file. - *@param a_result out parameter. A pointer + *@a_enc: the encoding of the file. + *@a_result: out parameter. A pointer *the build css object model. - *@param CR_OK upon successfull completion, an error code - *otherwise. + * + *Parses a css2 stylesheet contained + *in a file. + * + * Returns CR_OK upon succesful completion, an error code otherwise. */ enum CRStatus cr_om_parser_parse_file (CROMParser * a_this, @@ -955,12 +966,15 @@ cr_om_parser_parse_file (CROMParser * a_this, } /** - *The simpler method to parse a css2 file. - *@param a_file_path the css2 local file path. - *@param a_enc the file encoding. - *@param a_result out parameter. The returned css stylesheet. + * cr_om_parser_simply_parse_file: + *@a_file_path: the css2 local file path. + *@a_enc: the file encoding. + *@a_result: out parameter. The returned css stylesheet. *Must be freed by the caller using cr_stylesheet_destroy. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *The simpler method to parse a css2 file. + * + *Returns CR_OK upon successfull completion, an error code otherwise. *Note that this method uses cr_om_parser_parse_file() so both methods *have the same return values. */ @@ -990,14 +1004,18 @@ cr_om_parser_simply_parse_file (const guchar * a_file_path, } /** - *Parses three sheets located by their paths and build a cascade - *@param a_this the current instance of #CROMParser - *@param a_author_path the path to the author stylesheet - *@param a_user_path the path to the user stylesheet - *@param a_ua_path the path to the User Agent stylesheet - *@param a_result out parameter. The resulting cascade if the parsing + * cr_om_parser_parse_paths_to_cascade: + *@a_this: the current instance of #CROMParser + *@a_author_path: the path to the author stylesheet + *@a_user_path: the path to the user stylesheet + *@a_ua_path: the path to the User Agent stylesheet + *@a_encoding: the encoding of the sheets. + *@a_result: out parameter. The resulting cascade if the parsing *was okay - *@return CR_OK upon successful completion, an error code otherwise + * + *Parses three sheets located by their paths and build a cascade + * + *Returns CR_OK upon successful completion, an error code otherwise */ enum CRStatus cr_om_parser_parse_paths_to_cascade (CROMParser * a_this, @@ -1017,7 +1035,7 @@ cr_om_parser_parse_paths_to_cascade (CROMParser * a_this, g_return_val_if_fail (a_this, CR_BAD_PARAM_ERROR); - memset (sheets, 0, sizeof (sheets)); + memset (sheets, 0, sizeof (CRStyleSheet*) * 3); paths[0] = (guchar *) a_author_path; paths[1] = (guchar *) a_user_path; paths[2] = (guchar *) a_ua_path; @@ -1046,13 +1064,17 @@ cr_om_parser_parse_paths_to_cascade (CROMParser * a_this, } /** - *Parses three sheets located by their paths and build a cascade - *@param a_author_path the path to the author stylesheet - *@param a_user_path the path to the user stylesheet - *@param a_ua_path the path to the User Agent stylesheet - *@param a_result out parameter. The resulting cascade if the parsing + * cr_om_parser_simply_parse_paths_to_cascade: + *@a_author_path: the path to the author stylesheet + *@a_user_path: the path to the user stylesheet + *@a_ua_path: the path to the User Agent stylesheet + *@a_encoding: the encoding of the sheets. + *@a_result: out parameter. The resulting cascade if the parsing *was okay - *@return CR_OK upon successful completion, an error code otherwise + * + *Parses three sheets located by their paths and build a cascade + * + *Returns CR_OK upon successful completion, an error code otherwise */ enum CRStatus cr_om_parser_simply_parse_paths_to_cascade (const guchar * a_author_path, @@ -1083,8 +1105,10 @@ cr_om_parser_simply_parse_paths_to_cascade (const guchar * a_author_path, } /** + * cr_om_parser_destroy: + *@a_this: the current instance of #CROMParser. + * *Destructor of the #CROMParser. - *@param a_this the current instance of #CROMParser. */ void cr_om_parser_destroy (CROMParser * a_this) diff --git a/src/libcroco/cr-parser.c b/src/libcroco/cr-parser.c index 410f8f80f..6544a679f 100644 --- a/src/libcroco/cr-parser.c +++ b/src/libcroco/cr-parser.c @@ -24,7 +24,8 @@ */ /** - *@file + *@CRParser: + * *The definition of the #CRParser class. */ @@ -41,7 +42,7 @@ *===================================== * *One must keep in mind - *that css UA must comply with two syntax. + *that css UA must comply with two syntaxes. * *1/the specific syntax that defines the css language *for a given level of specificatin (e.g css2 syntax @@ -136,8 +137,9 @@ struct _CRParserPriv { #define CHARS_TAB_SIZE 12 /** + * IS_NUM: + *@a_char: the char to test. *return TRUE if the character is a number ([0-9]), FALSE otherwise - *@param a_char the char to test. */ #define IS_NUM(a_char) (((a_char) >= '0' && (a_char) <= '9')?TRUE:FALSE) @@ -161,16 +163,18 @@ if ((status) != CR_OK) \ } /** - *same as CHECK_PARSING_STATUS() but this one pushes an error - *on the parser error stack when an error arises. - *@param a_this the current instance of #CRParser . - *@param a_status the status to check. Is of type enum #CRStatus. - *@param a_is_exception in case of error, if is TRUE, the status + * CHECK_PARSING_STATUS_ERR: + *@a_this: the current instance of #CRParser . + *@a_status: the status to check. Is of type enum #CRStatus. + *@a_is_exception: in case of error, if is TRUE, the status *is set to CR_PARSING_ERROR before goto error. If is false, the *real low level status is kept and will be returned by the *upper level function that called this macro. Usally,this must *be set to FALSE. * + *same as CHECK_PARSING_STATUS() but this one pushes an error + *on the parser error stack when an error arises. + * */ #define CHECK_PARSING_STATUS_ERR(a_this, a_status, a_is_exception,\ a_err_msg, a_err_status) \ @@ -603,11 +607,13 @@ cr_parser_clear_errors (CRParser * a_this) } /** + * cr_parser_try_to_skip_spaces_and_comments: + *@a_this: the current instance of #CRParser. + * *Same as cr_parser_try_to_skip_spaces() but this one skips *spaces and comments. * - *@param a_this the current instance of #CRParser. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_try_to_skip_spaces_and_comments (CRParser * a_this) @@ -1483,6 +1489,9 @@ cr_parser_parse_property (CRParser * a_this, } /** + * cr_parser_parse_term: + *@a_term: out parameter. The successfully parsed term. + * *Parses a "term" as defined in the css2 spec, appendix D.1: *term ::= unary_operator? [NUMBER S* | PERCENTAGE S* | LENGTH S* | *EMS S* | EXS S* | ANGLE S* | TIME S* | FREQ S* | function ] | @@ -1490,8 +1499,7 @@ cr_parser_parse_property (CRParser * a_this, * *TODO: handle parsing of 'RGB' * - *@param a_term out parameter. The successfully parsed term. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_term (CRParser * a_this, CRTerm ** a_term) @@ -1636,15 +1644,17 @@ cr_parser_parse_term (CRParser * a_this, CRTerm ** a_term) } /** + * cr_parser_parse_simple_selector: + *@a_this: the "this pointer" of the current instance of #CRParser. + *@a_sel: out parameter. Is set to the successfully parsed simple + *selector. + * *Parses a "simple_selector" as defined by the css2 spec in appendix D.1 : *element_name? [ HASH | class | attrib | pseudo ]* S* *and where pseudo is: *pseudo ::= ':' [ IDENT | FUNCTION S* IDENT S* ')' ] * - *@Param a_this the "this pointer" of the current instance of #CRParser. - *@param a_sel out parameter. Is set to the successfully parsed simple - *selector. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ static enum CRStatus cr_parser_parse_simple_selector (CRParser * a_this, CRSimpleSel ** a_sel) @@ -1904,16 +1914,18 @@ cr_parser_parse_simple_selector (CRParser * a_this, CRSimpleSel ** a_sel) } /** - *Parses a "selector" as defined by the css2 spec in appendix D.1: - *selector ::= simple_selector [ combinator simple_selector ]* - * - *@param a_this the this pointer of the current instance of #CRParser. - *@param a_start a pointer to the + * cr_parser_parse_simple_sels: + *@a_this: the this pointer of the current instance of #CRParser. + *@a_start: a pointer to the *first chararcter of the successfully parsed *string. - *@param a_end a pointer to the last character of the successfully parsed + *@a_end: a pointer to the last character of the successfully parsed *string. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Parses a "selector" as defined by the css2 spec in appendix D.1: + *selector ::= simple_selector [ combinator simple_selector ]* + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ static enum CRStatus cr_parser_parse_simple_sels (CRParser * a_this, @@ -1980,11 +1992,14 @@ cr_parser_parse_simple_sels (CRParser * a_this, } /** - *Parses a comma separated list of selectors. - *@param a_this the current instance of #CRParser. - *@param a_selector the parsed list of comma separated + * cr_parser_parse_selector: + *@a_this: the current instance of #CRParser. + *@a_selector: the parsed list of comma separated *selectors. - *@return CR_OK upon successful completion, an error + * + *Parses a comma separated list of selectors. + * + *Returns CR_OK upon successful completion, an error *code otherwise. */ static enum CRStatus @@ -2098,16 +2113,17 @@ cr_parser_parse_selector (CRParser * a_this, } /** + * cr_parser_parse_function: + *@a_this: the "this pointer" of the current instance of #CRParser. + * + *@a_func_name: out parameter. The parsed function name + *@a_expr: out parameter. The successfully parsed term. + * *Parses a "function" as defined in css spec at appendix D.1: *function ::= FUNCTION S* expr ')' S* *FUNCTION ::= ident'(' * - *@param a_this the "this pointer" of the current instance of - *#CRParser. - * - *@param a_func_name out parameter. The parsed function name - *@param a_expr out parameter. The successfully parsed term. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ static enum CRStatus cr_parser_parse_function (CRParser * a_this, @@ -2185,13 +2201,15 @@ cr_parser_parse_function (CRParser * a_this, } /** + * cr_parser_parse_uri: + *@a_this: the current instance of #CRParser. + *@a_str: the successfully parsed url. + * *Parses an uri as defined by the css spec [4.1.1]: * URI ::= url\({w}{string}{w}\) * |url\({w}([!#$%&*-~]|{nonascii}|{escape})*{w}\) * - *@param a_this the current instance of #CRParser. - *@param a_str the successfully parsed url. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ static enum CRStatus cr_parser_parse_uri (CRParser * a_this, CRString ** a_str) @@ -2208,19 +2226,21 @@ cr_parser_parse_uri (CRParser * a_this, CRString ** a_str) } /** + * cr_parser_parse_string: + *@a_this: the current instance of #CRParser. + *@a_start: out parameter. Upon successfull completion, + *points to the beginning of the string, points to an undefined value + *otherwise. + *@a_end: out parameter. Upon successfull completion, points to + *the beginning of the string, points to an undefined value otherwise. + * *Parses a string type as defined in css spec [4.1.1]: * *string ::= {string1}|{string2} *string1 ::= \"([\t !#$%&(-~]|\\{nl}|\'|{nonascii}|{escape})*\" *string2 ::= \'([\t !#$%&(-~]|\\{nl}|\"|{nonascii}|{escape})*\' * - *@param a_this the current instance of #CRParser. - *@param a_start out parameter. Upon successfull completion, - *points to the beginning of the string, points to an undefined value - *otherwise. - *@param a_end out parameter. Upon successfull completion, points to - *the beginning of the string, points to an undefined value otherwise. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ static enum CRStatus cr_parser_parse_string (CRParser * a_this, CRString ** a_str) @@ -2720,13 +2740,13 @@ cr_parser_parse_stylesheet (CRParser * a_this) ****************************************/ /** + * cr_parser_new: + * @a_tknzr: the tokenizer to use for the parsing. + * *Creates a new parser to parse data *coming the input stream given in parameter. - *@param a_input the input stream of the parser. - *Note that the newly created parser will ref - *a_input and unref it when parsing reaches the - *end of the input stream. - *@return the newly created instance of #CRParser, + * + *Returns the newly created instance of #CRParser, *or NULL if an error occured. */ CRParser * @@ -2748,15 +2768,18 @@ cr_parser_new (CRTknzr * a_tknzr) } /** - *Instanciates a new parser from a memory buffer. - *@param a_buf the buffer to parse. - *@param a_len the length of the data in the buffer. - *@param a_enc the encoding of the input buffer a_buf. - *@param a_free_buf if set to TRUE, a_buf will be freed + * cr_parser_new_from_buf: + *@a_buf: the buffer to parse. + *@a_len: the length of the data in the buffer. + *@a_enc: the encoding of the input buffer a_buf. + *@a_free_buf: if set to TRUE, a_buf will be freed *during the destruction of the newly built instance *of #CRParser. If set to FALSE, it is up to the caller to *eventually free it. - *@return the newly built parser, or NULL if an error arises. + * + *Instanciates a new parser from a memory buffer. + * + *Returns the newly built parser, or NULL if an error arises. */ CRParser * cr_parser_new_from_buf (guchar * a_buf, @@ -2781,6 +2804,12 @@ cr_parser_new_from_buf (guchar * a_buf, return result; } +/** + * cr_parser_new_from_input: + * @a_input: the parser input stream to use. + * + * Returns a newly built parser input. + */ CRParser * cr_parser_new_from_input (CRInput * a_input) { @@ -2798,6 +2827,13 @@ cr_parser_new_from_input (CRInput * a_input) return result; } +/** + * cr_parser_new_from_file: + * @a_file_uri: the uri of the file to parse. + * @a_enc: the file encoding to use. + * + * Returns the newly built parser. + */ CRParser * cr_parser_new_from_file (const guchar * a_file_uri, enum CREncoding a_enc) { @@ -2816,10 +2852,13 @@ cr_parser_new_from_file (const guchar * a_file_uri, enum CREncoding a_enc) } /** + * cr_parser_set_sac_handler: + *@a_this: the "this pointer" of the current instance of #CRParser. + *@a_handler: the handler to set. + * *Sets a SAC document handler to the parser. - *@param a_this the "this pointer" of the current instance of #CRParser. - *@param a_handler the handler to set. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_set_sac_handler (CRParser * a_this, CRDocHandler * a_handler) @@ -2837,11 +2876,14 @@ cr_parser_set_sac_handler (CRParser * a_this, CRDocHandler * a_handler) } /** - *Gets the SAC document handler. - *@param a_this the "this pointer" of the current instance of + * cr_parser_get_sac_handler: + *@a_this: the "this pointer" of the current instance of *#CRParser. - *@param a_handler out parameter. The returned handler. - *@return CR_OK upon successfull completion, an error code + *@a_handler: out parameter. The returned handler. + * + *Gets the SAC document handler. + * + *Returns CR_OK upon successfull completion, an error code *otherwise. */ enum CRStatus @@ -2855,10 +2897,13 @@ cr_parser_get_sac_handler (CRParser * a_this, CRDocHandler ** a_handler) } /** + * cr_parser_set_default_sac_handler: + *@a_this: a pointer to the current instance of #CRParser. + * *Sets the SAC handler associated to the current instance *of #CRParser to the default SAC handler. - *@param a_this a pointer to the current instance of #CRParser. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_set_default_sac_handler (CRParser * a_this) @@ -2882,6 +2927,13 @@ cr_parser_set_default_sac_handler (CRParser * a_this) return status; } +/** + * cr_parser_set_use_core_grammar: + * @a_this: the current instance of #CRParser. + * @a_use_core_grammar: where to parse against the css core grammar. + * + * Returns CR_OK upon succesful completion, an error code otherwise. + */ enum CRStatus cr_parser_set_use_core_grammar (CRParser * a_this, gboolean a_use_core_grammar) @@ -2893,8 +2945,15 @@ cr_parser_set_use_core_grammar (CRParser * a_this, return CR_OK; } +/** + * cr_parser_get_use_core_grammar: + * @a_this: the current instance of #CRParser. + * @a_use_core_grammar: wether to use the core grammar or not. + * + * Returns CR_OK upon succesful completion, an error code otherwise. + */ enum CRStatus -cr_parser_get_use_core_grammar (CRParser * a_this, +cr_parser_get_use_core_grammar (CRParser const * a_this, gboolean * a_use_core_grammar) { g_return_val_if_fail (a_this && PRIVATE (a_this), CR_BAD_PARAM_ERROR); @@ -2905,11 +2964,15 @@ cr_parser_get_use_core_grammar (CRParser * a_this, } /** - *Parses a the given in parameter. - *@param a_this a pointer to the current instance of #CRParser. - *@param a_file_uri the uri to the file to load. For the time being, + * cr_parser_parse_file: + *@a_this: a pointer to the current instance of #CRParser. + *@a_file_uri: the uri to the file to load. For the time being, + *@a_enc: the encoding of the file to parse. *only local files are supported. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Parses a the given in parameter. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_file (CRParser * a_this, @@ -2934,9 +2997,16 @@ cr_parser_parse_file (CRParser * a_this, } /** + * cr_parser_parse_expr: + * @a_this: the current instance of #CRParser. + * @a_expr: out parameter. the parsed expression. + * *Parses an expression as defined by the css2 spec in appendix *D.1: *expr: term [ operator term ]* + * + * + * Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_parser_parse_expr (CRParser * a_this, CRTerm ** a_expr) @@ -3033,13 +3103,17 @@ cr_parser_parse_expr (CRParser * a_this, CRTerm ** a_expr) } /** + * cr_parser_parse_prio: + *@a_this: the current instance of #CRParser. + *@a_prio: a string representing the priority. + *Today, only "!important" is returned as only this + *priority is defined by css2. + * *Parses a declaration priority as defined by *the css2 grammar in appendix C: *prio: IMPORTANT_SYM S* - *@param a_this the current instance of #CRParser. - *@param a_prio a string representing the priority. - *Today, only "!important" is returned as only this - *priority is defined by css2. + * + * Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_parser_parse_prio (CRParser * a_this, CRString ** a_prio) @@ -3078,17 +3152,19 @@ cr_parser_parse_prio (CRParser * a_this, CRString ** a_prio) } /** + * cr_parser_parse_declaration: + *@a_this: the "this pointer" of the current instance of #CRParser. + *@a_property: the successfully parsed property. The caller + * *must* free the returned pointer. + *@a_expr: the expression that represents the attribute value. + *The caller *must* free the returned pointer. + * *TODO: return the parsed priority, so that *upper layers can take benefit from it. *Parses a "declaration" as defined by the css2 spec in appendix D.1: *declaration ::= [property ':' S* expr prio?]? * - *@param a_this the "this pointer" of the current instance of #CRParser. - *@param a_property the successfully parsed property. The caller - * *must* free the returned pointer. - *@param a_expr the expression that represents the attribute value. - *The caller *must* free the returned pointer. - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_declaration (CRParser * a_this, @@ -3175,11 +3251,14 @@ cr_parser_parse_declaration (CRParser * a_this, } /** + * cr_parser_parse_statement_core: + *@a_this: the current instance of #CRParser. + * *Parses a statement as defined by the css core grammar in *chapter 4.1 of the css2 spec. *statement : ruleset | at-rule; - *@param a_this the current instance of #CRParser. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_statement_core (CRParser * a_this) @@ -3231,6 +3310,9 @@ cr_parser_parse_statement_core (CRParser * a_this) } /** + * cr_parser_parse_ruleset: + *@a_this: the "this pointer" of the current instance of #CRParser. + * *Parses a "ruleset" as defined in the css2 spec at appendix D.1. *ruleset ::= selector [ ',' S* selector ]* *'{' S* declaration? [ ';' S* declaration? ]* '}' S*; @@ -3239,8 +3321,8 @@ cr_parser_parse_statement_core (CRParser * a_this) *callbacks whenever it encounters some specific constructions. *See the documentation of #CRDocHandler (the SAC handler) to know *when which SAC handler is called. - *@param a_this the "this pointer" of the current instance of #CRParser. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_ruleset (CRParser * a_this) @@ -3255,6 +3337,7 @@ cr_parser_parse_ruleset (CRParser * a_this) CRSelector *selector = NULL; gboolean start_selector = FALSE, is_important = FALSE; + CRParsingLocation end_parsing_location; g_return_val_if_fail (a_this, CR_BAD_PARAM_ERROR); @@ -3369,12 +3452,14 @@ cr_parser_parse_ruleset (CRParser * a_this) end_of_ruleset: cr_parser_try_to_skip_spaces_and_comments (a_this); + cr_parser_get_parsing_location (a_this, &end_parsing_location); READ_NEXT_CHAR (a_this, &cur_char); ENSURE_PARSING_COND_ERR (a_this, cur_char == '}', (guchar *)"while parsing rulset: current char must be a '}'", CR_SYNTAX_ERROR); + selector->location = end_parsing_location; if (PRIVATE (a_this)->sac_handler && PRIVATE (a_this)->sac_handler->end_selector) { PRIVATE (a_this)->sac_handler->end_selector @@ -3431,29 +3516,29 @@ cr_parser_parse_ruleset (CRParser * a_this) } /** - *Parses an 'import' declaration as defined in the css2 spec - *in appendix D.1: - * - *import ::= - *@import [STRING|URI] S* [ medium [ ',' S* medium]* ]? ';' S* - * - *@param a_this the "this pointer" of the current instance + * cr_parser_parse_import: + *@a_this: the "this pointer" of the current instance *of #CRParser. - * - *@param a_medium_list out parameter. A linked list of + *@a_media_list: out parameter. A linked list of *#CRString *Each CRString is a string that contains *a 'medium' declaration part of the successfully *parsed 'import' declaration. - * - *@param a_import_string out parameter. + *@a_import_string: out parameter. *A string that contains the 'import *string". The import string can be either an uri (if it starts with *the substring "uri(") or a any other css2 string. Note that * *a_import_string must be initially set to NULL or else, this function *will return CR_BAD_PARAM_ERROR. + *@a_location: the location (line, column) where the import has been parsed * - *@return CR_OK upon sucessfull completion, an error code otherwise. + *Parses an 'import' declaration as defined in the css2 spec + *in appendix D.1: + * + *import ::= + *\@import [STRING|URI] S* [ medium [ ',' S* medium]* ]? ';' S* + * + *Returns CR_OK upon sucessfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_import (CRParser * a_this, @@ -3602,16 +3687,19 @@ cr_parser_parse_import (CRParser * a_this, } /** + * cr_parser_parse_media: + *@a_this: the "this pointer" of the current instance of #CRParser. + * *Parses a 'media' declaration as specified in the css2 spec at *appendix D.1: * - *media ::= @media S* medium [ ',' S* medium ]* '{' S* ruleset* '}' S* + *media ::= \@media S* medium [ ',' S* medium ]* '{' S* ruleset* '}' S* * *Note that this function calls the required sac handlers during the parsing *to notify media productions. See #CRDocHandler to know the callback called - *during @media parsing. - *@param a_this the "this pointer" of the current instance of #CRParser. - *@return CR_OK upon successfull completion, an error code otherwise. + *during \@media parsing. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_media (CRParser * a_this) @@ -3770,15 +3858,18 @@ cr_parser_parse_media (CRParser * a_this) } /** - *Parses '@page' rule as specified in the css2 spec in appendix D.1: + * cr_parser_parse_page: + *@a_this: the "this pointer" of the current instance of #CRParser. + * + *Parses '\@page' rule as specified in the css2 spec in appendix D.1: *page ::= PAGE_SYM S* IDENT? pseudo_page? S* *'{' S* declaration [ ';' S* declaration ]* '}' S* * *This function also calls the relevant SAC handlers whenever it *encounters a construction that must *be reported to the calling application. - *@param a_this the "this pointer" of the current instance of #CRParser. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_page (CRParser * a_this) @@ -4018,16 +4109,18 @@ cr_parser_parse_page (CRParser * a_this) } /** + * cr_parser_parse_charset: + *@a_this: the "this pointer" of the current instance of #CRParser. + *@a_value: out parameter. The actual parsed value of the charset + *declararation. Note that for safety check reasons, *a_value must be + *set to NULL. + *@a_charset_sym_location: the parsing location of the charset rule + * *Parses a charset declaration as defined implictly by the css2 spec in *appendix D.1: *charset ::= CHARSET_SYM S* STRING S* ';' * - *@param a_this the "this pointer" of the current instance of #CRParser. - *@param a_value out parameter. The actual parsed value of the charset - *declararation. Note that for safety check reasons, *a_value must be - *set to NULL. - *@param a_charset_sym_location the parsing location of - *@return CR_OK upon successfull completion, an error code otherwise. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_charset (CRParser * a_this, CRString ** a_value, @@ -4107,14 +4200,18 @@ cr_parser_parse_charset (CRParser * a_this, CRString ** a_value, } /** - *Parses the "@font-face" rule specified in the css1 spec in + * cr_parser_parse_font_face: + *@a_this: the current instance of #CRParser. + * + *Parses the "\@font-face" rule specified in the css1 spec in *appendix D.1: * *font_face ::= FONT_FACE_SYM S* *'{' S* declaration [ ';' S* declaration ]* '}' S* * *This function will call SAC handlers whenever it is necessary. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_parser_parse_font_face (CRParser * a_this) @@ -4264,11 +4361,14 @@ cr_parser_parse_font_face (CRParser * a_this) } /** + * cr_parser_parse: + *@a_this: the current instance of #CRParser. + * *Parses the data that comes from the *input previously associated to the current instance of *#CRParser. - *@param a_this the current instance of #CRParser. - *@return CR_OK ; + * + *Returns CR_OK upon succesful completion, an error code otherwise. */ enum CRStatus cr_parser_parse (CRParser * a_this) @@ -4287,6 +4387,13 @@ cr_parser_parse (CRParser * a_this) return status; } +/** + * cr_parser_set_tknzr: + * @a_this: the current instance of #CRParser; + * @a_tknzr: the new tokenizer. + * + * Returns CR_OK upon successful completion, an error code otherwise. + */ enum CRStatus cr_parser_set_tknzr (CRParser * a_this, CRTknzr * a_tknzr) { @@ -4305,10 +4412,13 @@ cr_parser_set_tknzr (CRParser * a_this, CRTknzr * a_tknzr) } /** + * cr_parser_get_tknzr: + *@a_this: the current instance of #CRParser + *@a_tknzr: out parameter. The returned tokenizer + * *Getter of the parser's underlying tokenizer - *@param a_this the current instance of #CRParser - *@param a_tknzr out parameter. The returned tokenizer - *@return CR_OK upon succesful completion, an error code + * + *Returns CR_OK upon succesful completion, an error code *otherwise */ enum CRStatus @@ -4322,14 +4432,17 @@ cr_parser_get_tknzr (CRParser * a_this, CRTknzr ** a_tknzr) } /** + * cr_parser_get_parsing_location: + *@a_this: the current instance of #CRParser + *@a_loc: the parsing location to get. + * *Gets the current parsing location. - *@param a_this the current instance of #CRParser - *@param a_loc the parsing location to get. - *@return CR_OK upon succesful completion, an error code + * + *Returns CR_OK upon succesful completion, an error code *otherwise. */ enum CRStatus -cr_parser_get_parsing_location (CRParser *a_this, +cr_parser_get_parsing_location (CRParser const *a_this, CRParsingLocation *a_loc) { g_return_val_if_fail (a_this @@ -4341,12 +4454,15 @@ cr_parser_get_parsing_location (CRParser *a_this, } /** + * cr_parser_parse_buf: + *@a_this: the current instance of #CRparser + *@a_buf: the input buffer + *@a_len: the length of the input buffer + *@a_enc: the encoding of the buffer + * *Parses a stylesheet from a buffer - *@param a_this the current instance of #CRparser - *@param a_buf the input buffer - *@param a_len the length of the input buffer - *@param a_enc the encoding of the buffer - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_parser_parse_buf (CRParser * a_this, @@ -4372,10 +4488,12 @@ cr_parser_parse_buf (CRParser * a_this, } /** + * cr_parser_destroy: + *@a_this: the current instance of #CRParser to + *destroy. + * *Destroys the current instance *of #CRParser. - *@param a_this the current instance of #CRParser to - *destroy. */ void cr_parser_destroy (CRParser * a_this) diff --git a/src/libcroco/cr-parser.h b/src/libcroco/cr-parser.h index 1534afb86..6dce9439e 100644 --- a/src/libcroco/cr-parser.h +++ b/src/libcroco/cr-parser.h @@ -68,7 +68,7 @@ enum CRStatus cr_parser_set_tknzr (CRParser *a_this, CRTknzr *a_tknzr) ; enum CRStatus cr_parser_get_tknzr (CRParser *a_this, CRTknzr **a_tknzr) ; -enum CRStatus cr_parser_get_parsing_location (CRParser *a_this, CRParsingLocation *a_loc) ; +enum CRStatus cr_parser_get_parsing_location (CRParser const *a_this, CRParsingLocation *a_loc) ; enum CRStatus cr_parser_try_to_skip_spaces_and_comments (CRParser *a_this) ; @@ -81,7 +81,7 @@ enum CRStatus cr_parser_get_sac_handler (CRParser *a_this, enum CRStatus cr_parser_set_use_core_grammar (CRParser *a_this, gboolean a_use_core_grammar) ; -enum CRStatus cr_parser_get_use_core_grammar (CRParser *a_this, +enum CRStatus cr_parser_get_use_core_grammar (CRParser const *a_this, gboolean *a_use_core_grammar) ; enum CRStatus cr_parser_parse (CRParser *a_this) ; diff --git a/src/libcroco/cr-parsing-location.c b/src/libcroco/cr-parsing-location.c index 38a75a6e6..a883de933 100644 --- a/src/libcroco/cr-parsing-location.c +++ b/src/libcroco/cr-parsing-location.c @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -25,14 +25,17 @@ #include "cr-parsing-location.h" /** - *@file + *@CRParsingLocation: + * *Definition of the #CRparsingLocation class. */ /** + * cr_parsing_location_new: *Instanciates a new parsing location. - *@return the newly instanciated #CRParsingLocation. + * + *Returns the newly instanciated #CRParsingLocation. *Must be freed by cr_parsing_location_destroy() */ CRParsingLocation * @@ -49,9 +52,12 @@ cr_parsing_location_new (void) } /** + * cr_parsing_location_init: + *@a_this: the current instance of #CRParsingLocation. + * *Initializes the an instance of #CRparsingLocation. - *@param a_this the current instance of #CRParsingLocation. - *@return CR_OK upon + * + *Returns CR_OK upon succesful completion, an error code otherwise. */ enum CRStatus cr_parsing_location_init (CRParsingLocation *a_this) @@ -63,16 +69,19 @@ cr_parsing_location_init (CRParsingLocation *a_this) } /** - *Copies an instance of CRParsingLocation into another one. - *@param a_to the destination of the copy. + * cr_parsing_location_copy: + *@a_to: the destination of the copy. *Must be allocated by the caller. - *@param a_from the source of the copy. - *@return CR_OK upon succesful completion, an error code + *@a_from: the source of the copy. + * + *Copies an instance of CRParsingLocation into another one. + * + *Returns CR_OK upon succesful completion, an error code *otherwise. */ enum CRStatus cr_parsing_location_copy (CRParsingLocation *a_to, - CRParsingLocation *a_from) + CRParsingLocation const *a_from) { g_return_val_if_fail (a_to && a_from, CR_BAD_PARAM_ERROR) ; @@ -81,13 +90,15 @@ cr_parsing_location_copy (CRParsingLocation *a_to, } /** - *@param a_this the current instance of #CRParsingLocation. - *@param a_mask a bitmap that defines which parts of the + * cr_parsing_location_to_string: + *@a_this: the current instance of #CRParsingLocation. + *@a_mask: a bitmap that defines which parts of the *parsing location are to be serialized (line, column or byte offset) - *@return the serialized string or NULL in case of an error. + * + *Returns the serialized string or NULL in case of an error. */ gchar * -cr_parsing_location_to_string (CRParsingLocation *a_this, +cr_parsing_location_to_string (CRParsingLocation const *a_this, enum CRParsingLocationSerialisationMask a_mask) { gchar *str = NULL ; @@ -122,8 +133,14 @@ cr_parsing_location_to_string (CRParsingLocation *a_this, return str ; } +/** + * cr_parsing_location_dump: + * @a_this: current instance of #CRParsingLocation + * @a_mask: the serialization mask. + * @a_fp: the file pointer to dump the parsing location to. + */ void -cr_parsing_location_dump (CRParsingLocation *a_this, +cr_parsing_location_dump (CRParsingLocation const *a_this, enum CRParsingLocationSerialisationMask a_mask, FILE *a_fp) { @@ -139,9 +156,11 @@ cr_parsing_location_dump (CRParsingLocation *a_this, } /** - *Destroys the current instance of #CRParsingLocation - *@param a_this the current instance of #CRParsingLocation. Must + * cr_parsing_location_destroy: + *@a_this: the current instance of #CRParsingLocation. Must *have been allocated with cr_parsing_location_new(). + * + *Destroys the current instance of #CRParsingLocation */ void cr_parsing_location_destroy (CRParsingLocation *a_this) diff --git a/src/libcroco/cr-parsing-location.h b/src/libcroco/cr-parsing-location.h index 877c0507f..b8064a560 100644 --- a/src/libcroco/cr-parsing-location.h +++ b/src/libcroco/cr-parsing-location.h @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -54,11 +54,11 @@ CRParsingLocation * cr_parsing_location_new (void) ; enum CRStatus cr_parsing_location_init (CRParsingLocation *a_this) ; enum CRStatus cr_parsing_location_copy (CRParsingLocation *a_to, - CRParsingLocation *a_from) ; + CRParsingLocation const *a_from) ; -gchar * cr_parsing_location_to_string (CRParsingLocation *a_this, +gchar * cr_parsing_location_to_string (CRParsingLocation const *a_this, enum CRParsingLocationSerialisationMask a_mask) ; -void cr_parsing_location_dump (CRParsingLocation *a_this, +void cr_parsing_location_dump (CRParsingLocation const *a_this, enum CRParsingLocationSerialisationMask a_mask, FILE *a_fp) ; diff --git a/src/libcroco/cr-prop-list.c b/src/libcroco/cr-prop-list.c index 551f0b8ee..c0eaaf494 100644 --- a/src/libcroco/cr-prop-list.c +++ b/src/libcroco/cr-prop-list.c @@ -62,10 +62,13 @@ cr_prop_list_allocate (void) ***************/ /** + * cr_prop_list_append: + *@a_this: the current instance of #CRPropList + *@a_to_append: the property list to append + * *Appends a property list to the current one. - *@param a_this the current instance of #CRPropList - *@param a_to_append the property list to append - *@return the resulting prop list, or NULL if an error + * + *Returns the resulting prop list, or NULL if an error *occured */ CRPropList * @@ -89,12 +92,14 @@ cr_prop_list_append (CRPropList * a_this, CRPropList * a_to_append) } /** + * cr_prop_list_append2: *Appends a pair of prop/declaration to *the current prop list. - *@param a_this the current instance of #CRPropList - *@param a_prop the property to consider - *@param a_decl the declaration to consider - *@return the resulting property list, or NULL in case + *@a_this: the current instance of #CRPropList + *@a_prop: the property to consider + *@a_decl: the declaration to consider + * + *Returns the resulting property list, or NULL in case *of an error. */ CRPropList * @@ -118,9 +123,12 @@ cr_prop_list_append2 (CRPropList * a_this, } /** + * cr_prop_list_prepend: + *@a_this: the current instance of #CRPropList + *@a_to_prepend: the new list to prepend. + * *Prepends a list to the current list - *@param a_this the current instance of #CRPropList - *@param the new list to prepend. + *Returns the new properties list. */ CRPropList * cr_prop_list_prepend (CRPropList * a_this, CRPropList * a_to_prepend) @@ -141,32 +149,39 @@ cr_prop_list_prepend (CRPropList * a_this, CRPropList * a_to_prepend) } /** - *Prepends a list to the current list - *@param a_this the current instance of #CRPropList - *@param the new list to prepend. + * cr_prop_list_prepend2: + *@a_this: the current instance of #CRPropList + *@a_prop_name: property name to append + *@a_decl: the property value to append. + * + *Prepends a propertie to a list of properties + * + *Returns the new property list. */ CRPropList * cr_prop_list_prepend2 (CRPropList * a_this, - CRString * a_prop, CRDeclaration * a_decl) + CRString * a_prop_name, CRDeclaration * a_decl) { CRPropList *list = NULL, *result = NULL; g_return_val_if_fail (a_this && PRIVATE (a_this) - && a_prop && a_decl, NULL); + && a_prop_name && a_decl, NULL); list = cr_prop_list_allocate (); g_return_val_if_fail (list, NULL); - PRIVATE (list)->prop = a_prop; + PRIVATE (list)->prop = a_prop_name; PRIVATE (list)->decl = a_decl; result = cr_prop_list_prepend (a_this, list); return result; } /** + * cr_prop_list_set_prop: + *@a_this: the current instance of #CRPropList + *@a_prop: the property to set + * *Sets the property of a CRPropList - *@param a_this the current instance of #CRPropList - *@param a_prop the property to set */ enum CRStatus cr_prop_list_set_prop (CRPropList * a_this, CRString * a_prop) @@ -179,15 +194,18 @@ cr_prop_list_set_prop (CRPropList * a_this, CRString * a_prop) } /** + * cr_prop_list_get_prop: + *@a_this: the current instance of #CRPropList + *@a_prop: out parameter. The returned property + * *Getter of the property associated to the current instance *of #CRPropList - *@param a_this the current instance of #CRPropList - *@param a_prop out parameter. The returned property - *@return CR_OK upon successful completion, an error code + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus -cr_prop_list_get_prop (CRPropList * a_this, CRString ** a_prop) +cr_prop_list_get_prop (CRPropList const * a_this, CRString ** a_prop) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_prop, CR_BAD_PARAM_ERROR); @@ -196,6 +214,13 @@ cr_prop_list_get_prop (CRPropList * a_this, CRString ** a_prop) return CR_OK; } +/** + * cr_prop_list_set_decl: + * @a_this: the current instance of #CRPropList + * @a_decl: the new property value. + * + * Returns CR_OK upon successful completion, an error code otherwise. + */ enum CRStatus cr_prop_list_set_decl (CRPropList * a_this, CRDeclaration * a_decl) { @@ -206,8 +231,15 @@ cr_prop_list_set_decl (CRPropList * a_this, CRDeclaration * a_decl) return CR_OK; } +/** + * cr_prop_list_get_decl: + * @a_this: the current instance of #CRPropList + * @a_decl: out parameter. The property value + * + * Returns CR_OK upon successful completion. + */ enum CRStatus -cr_prop_list_get_decl (CRPropList * a_this, CRDeclaration ** a_decl) +cr_prop_list_get_decl (CRPropList const * a_this, CRDeclaration ** a_decl) { g_return_val_if_fail (a_this && PRIVATE (a_this) && a_decl, CR_BAD_PARAM_ERROR); @@ -217,12 +249,15 @@ cr_prop_list_get_decl (CRPropList * a_this, CRDeclaration ** a_decl) } /** - *Lookup a given property/declaration pair - *@param a_this the current instance of #CRPropList - *@param a_prop the property to lookup - *@param a_prop_list out parameter. The property/declaration + * cr_prop_list_lookup_prop: + *@a_this: the current instance of #CRPropList + *@a_prop: the property to lookup + *@a_prop_list: out parameter. The property/declaration *pair found (if and only if the function returned code if CR_OK) - *@return CR_OK if a prop/decl pair has been found, + * + *Lookup a given property/declaration pair + * + *Returns CR_OK if a prop/decl pair has been found, *CR_VALUE_NOT_FOUND_ERROR if not, or an error code if something *bad happens. */ @@ -259,11 +294,12 @@ cr_prop_list_lookup_prop (CRPropList * a_this, } /** + * cr_prop_list_get_next: + *@a_this: the current instance of CRPropList + * *Gets the next prop/decl pair in the list - *@param a_this the current instance of CRPropList - *@param the next prop/decl pair, or NULL if we - *reached the end of the list. - *@return the next prop/declaration pair of the list, + * + *Returns the next prop/declaration pair of the list, *or NULL if we reached end of list (or if an error occurs) */ CRPropList * @@ -275,11 +311,12 @@ cr_prop_list_get_next (CRPropList * a_this) } /** + * cr_prop_list_get_prev: + *@a_this: the current instance of CRPropList + * *Gets the previous prop/decl pair in the list - *@param a_this the current instance of CRPropList - *@param the previous prop/decl pair, or NULL if we - *reached the end of the list. - *@return the previous prop/declaration pair of the list, + * + *Returns the previous prop/declaration pair of the list, *or NULL if we reached end of list (or if an error occurs) */ CRPropList * @@ -291,10 +328,13 @@ cr_prop_list_get_prev (CRPropList * a_this) } /** + * cr_prop_list_unlink: + *@a_this: the current list of prop/decl pairs + *@a_pair: the prop/decl pair to unlink. + * *Unlinks a prop/decl pair from the list - *@param a_this the current list of prop/decl pairs - *@param a_pair the prop/decl pair to unlink. - *@return the new list or NULL in case of an error. + * + *Returns the new list or NULL in case of an error. */ CRPropList * cr_prop_list_unlink (CRPropList * a_this, CRPropList * a_pair) @@ -330,6 +370,10 @@ cr_prop_list_unlink (CRPropList * a_this, CRPropList * a_pair) return a_this; } +/** + * cr_prop_list_destroy: + * @a_this: the current instance of #CRPropList + */ void cr_prop_list_destroy (CRPropList * a_this) { diff --git a/src/libcroco/cr-prop-list.h b/src/libcroco/cr-prop-list.h index a003be260..797ba43ea 100644 --- a/src/libcroco/cr-prop-list.h +++ b/src/libcroco/cr-prop-list.h @@ -53,7 +53,7 @@ CRPropList * cr_prop_list_prepend2 (CRPropList *a_this, enum CRStatus cr_prop_list_set_prop (CRPropList *a_this, CRString *a_prop) ; -enum CRStatus cr_prop_list_get_prop (CRPropList *a_this, +enum CRStatus cr_prop_list_get_prop (CRPropList const *a_this, CRString **a_prop) ; enum CRStatus cr_prop_list_lookup_prop (CRPropList *a_this, @@ -67,7 +67,7 @@ CRPropList * cr_prop_list_get_prev (CRPropList *a_this) ; enum CRStatus cr_prop_list_set_decl (CRPropList *a_this, CRDeclaration *a_decl); -enum CRStatus cr_prop_list_get_decl (CRPropList *a_this, +enum CRStatus cr_prop_list_get_decl (CRPropList const *a_this, CRDeclaration **a_decl) ; CRPropList * cr_prop_list_unlink (CRPropList *a_this, diff --git a/src/libcroco/cr-pseudo.c b/src/libcroco/cr-pseudo.c index abb4f9bd4..7799a8bbb 100644 --- a/src/libcroco/cr-pseudo.c +++ b/src/libcroco/cr-pseudo.c @@ -24,13 +24,15 @@ #include "cr-pseudo.h" /** - *@file + *@CRPseudo: *The definition of the #CRPseudo class. */ /** + * cr_pseudo_new: *Constructor of the #CRPseudo class. - *@return the newly build instance. + * + *Returns the newly build instance. */ CRPseudo * cr_pseudo_new (void) @@ -40,8 +42,15 @@ cr_pseudo_new (void) return result; } +/** + * cr_pseudo_to_string: + * @a_this: the current instance of #CRPseud. + * + * Returns the serialized pseudo. Caller must free the returned + * string using g_free(). + */ guchar * -cr_pseudo_to_string (CRPseudo * a_this) +cr_pseudo_to_string (CRPseudo const * a_this) { guchar *result = NULL; @@ -105,12 +114,15 @@ cr_pseudo_to_string (CRPseudo * a_this) } /** + * cr_pseudo_dump: + *@a_this: the current instance of pseudo + *@a_fp: the destination file pointer. + * *Dumps the pseudo to a file. - *@param a_this the current instance of pseudo - *@param a_fp the destination file pointer. + * */ void -cr_pseudo_dump (CRPseudo * a_this, FILE * a_fp) +cr_pseudo_dump (CRPseudo const * a_this, FILE * a_fp) { guchar *tmp_str = NULL; @@ -125,8 +137,10 @@ cr_pseudo_dump (CRPseudo * a_this, FILE * a_fp) } /** + * cr_pseudo_destroy: + *@a_this: the current instance to destroy. + * *destructor of the #CRPseudo class. - *@param a_this the current instance to destroy. */ void cr_pseudo_destroy (CRPseudo * a_this) diff --git a/src/libcroco/cr-pseudo.h b/src/libcroco/cr-pseudo.h index 6de6c9e21..8917da45e 100644 --- a/src/libcroco/cr-pseudo.h +++ b/src/libcroco/cr-pseudo.h @@ -53,9 +53,9 @@ struct _CRPseudo CRPseudo * cr_pseudo_new (void) ; -guchar * cr_pseudo_to_string (CRPseudo *a_this) ; +guchar * cr_pseudo_to_string (CRPseudo const *a_this) ; -void cr_pseudo_dump (CRPseudo *a_this, FILE *a_fp) ; +void cr_pseudo_dump (CRPseudo const *a_this, FILE *a_fp) ; void cr_pseudo_destroy (CRPseudo *a_this) ; diff --git a/src/libcroco/cr-rgb.c b/src/libcroco/cr-rgb.c index b9f78ddba..1a16a2826 100644 --- a/src/libcroco/cr-rgb.c +++ b/src/libcroco/cr-rgb.c @@ -180,8 +180,11 @@ static CRRgb gv_standard_colors[] = { }; /** + * cr_rgb_new: + * *The default constructor of #CRRgb. - *@return the newly built instance of #CRRgb + * + *Returns the newly built instance of #CRRgb */ CRRgb * cr_rgb_new (void) @@ -199,13 +202,16 @@ cr_rgb_new (void) } /** - *A constructor of #CRRgb. - *@param a_red the red component of the color. - *@param a_green the green component of the color. - *@param a_blue the blue component of the color. - *@param a_unit the unit of the rgb values. + * cr_rgb_new_with_vals: + *@a_red: the red component of the color. + *@a_green: the green component of the color. + *@a_blue: the blue component of the color. + *@a_unit: the unit of the rgb values. *(either percentage or integer values) - *@return the newly built instance of #CRRgb. + * + *A constructor of #CRRgb. + * + *Returns the newly built instance of #CRRgb. */ CRRgb * cr_rgb_new_with_vals (gulong a_red, gulong a_green, @@ -226,13 +232,16 @@ cr_rgb_new_with_vals (gulong a_red, gulong a_green, } /** + * cr_rgb_to_string: + *@a_this: the instance of #CRRgb to serialize. + * *Serializes the rgb into a zero terminated string. - *@param a_this the instance of #CRRgb to serialize. - *@return the zero terminated string containing the serialized + * + *Returns the zero terminated string containing the serialized *rgb. MUST BE FREED by the caller using g_free(). */ guchar * -cr_rgb_to_string (CRRgb * a_this) +cr_rgb_to_string (CRRgb const * a_this) { gchar *result = NULL; GString *str_buf = (GString *)g_string_new (NULL); @@ -267,14 +276,16 @@ cr_rgb_to_string (CRRgb * a_this) } /** + * cr_rgb_dump: + *@a_this: the "this pointer" of + *the current instance of #CRRgb. + *@a_fp: the destination file pointer. + * *Dumps the current instance of #CRRgb *to a file. - *@param a_this the "this pointer" of - *the current instance of #CRRgb. - *@param a_fp the destination file pointer. */ void -cr_rgb_dump (CRRgb * a_this, FILE * a_fp) +cr_rgb_dump (CRRgb const * a_this, FILE * a_fp) { guchar *str = NULL; @@ -290,10 +301,13 @@ cr_rgb_dump (CRRgb * a_this, FILE * a_fp) } /** + * cr_rgb_compute_from_percentage: + *@a_this: the current instance of #CRRgb + * *If the rgb values are expressed in percentage, *compute their real value. - *@param a_this the current instance of #CRRgb - *@return + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_rgb_compute_from_percentage (CRRgb * a_this) @@ -310,12 +324,15 @@ cr_rgb_compute_from_percentage (CRRgb * a_this) } /** + * cr_rgb_set: + *@a_this: the current instance of #CRRgb. + *@a_red: the red value. + *@a_green: the green value. + *@a_blue: the blue value. + * *Sets rgb values to the RGB. - *@param a_this the current instance of #CRRgb. - *@param a_red the red value. - *@param a_green the green value. - *@param a_blue the blue value. - *@return CR_OK upon successful completion, an error code + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus @@ -340,11 +357,14 @@ cr_rgb_set (CRRgb * a_this, gulong a_red, } /** + * cr_rgb_set_to_inherit: + *@a_this: the current instance of #CRRgb + * *sets the value of the rgb to inherit. *Look at the css spec from chapter 6.1 to 6.2 to understand *the meaning of "inherit". - *@param a_this the current instance of #CRRgb * + * Returns CR_OK upon succesful completion, an error code otherwise. */ enum CRStatus cr_rgb_set_to_inherit (CRRgb *a_this, gboolean a_inherit) @@ -356,8 +376,15 @@ cr_rgb_set_to_inherit (CRRgb *a_this, gboolean a_inherit) return CR_OK ; } +/** + * cr_rgb_is_set_to_inherit: + * + * @a_this: the current instance of #CRRgb. + * + * Returns TRUE if the rgb is set to the value "inherit", FALSE otherwise. + */ gboolean -cr_rgb_is_set_to_inherit (CRRgb *a_this) +cr_rgb_is_set_to_inherit (CRRgb const *a_this) { g_return_val_if_fail (a_this, CR_BAD_PARAM_ERROR) ; @@ -365,15 +392,18 @@ cr_rgb_is_set_to_inherit (CRRgb *a_this) } /** + * cr_rgb_is_set_to_transparent: + *@a_this: the current instance of + *#CRRgb + * *Tests if the rgb is set to the *value "transparent" or not. - *@param a_this the current instance of - *#CRRgb - *@return TRUE if the rgb has been set to + * + *Returns TRUE if the rgb has been set to *transparent, FALSE otherwise. */ gboolean -cr_rgb_is_set_to_transparent (CRRgb *a_this) +cr_rgb_is_set_to_transparent (CRRgb const *a_this) { g_return_val_if_fail (a_this, FALSE) ; return a_this->is_transparent ; @@ -381,9 +411,12 @@ cr_rgb_is_set_to_transparent (CRRgb *a_this) /** + * cr_rgb_set_to_transparent: + *@a_this: the current instance of #CRRgb + *@a_is_transparent: set to transparent or not. + * *Sets the rgb to the "transparent" value (or not) - *@param a_this the current instance of #CRRgb - *@param a_is_transparent set to transparent or not. + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_rgb_set_to_transparent (CRRgb *a_this, @@ -395,13 +428,16 @@ cr_rgb_set_to_transparent (CRRgb *a_this, } /** + * cr_rgb_set_from_rgb: + *@a_this: the current instance of #CRRgb. + *@a_rgb: the rgb to "copy" + * *Sets the rgb from an other one. - *@param a_this the current instance of #CRRgb. - *@param a_rgb the rgb to "copy" - *@return CR_OK upon successful completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_rgb_set_from_rgb (CRRgb * a_this, CRRgb * a_rgb) +cr_rgb_set_from_rgb (CRRgb * a_this, CRRgb const * a_rgb) { g_return_val_if_fail (a_this && a_rgb, CR_BAD_PARAM_ERROR); @@ -410,6 +446,13 @@ cr_rgb_set_from_rgb (CRRgb * a_this, CRRgb * a_rgb) return CR_OK; } +/** + * cr_rgb_set_from_name: + * @a_this: the current instance of #CRRgb + * @a_color_name: the color name + * + * Returns CR_OK upon successful completion, an error code otherwise. + */ enum CRStatus cr_rgb_set_from_name (CRRgb * a_this, const guchar * a_color_name) { @@ -433,6 +476,13 @@ cr_rgb_set_from_name (CRRgb * a_this, const guchar * a_color_name) return status; } +/** + * cr_rgb_set_from_hex_str: + * @a_this: the current instance of #CRRgb + * @a_hex: the hexadecimal value to set. + * + * Returns CR_OK upon successful completion. + */ enum CRStatus cr_rgb_set_from_hex_str (CRRgb * a_this, const guchar * a_hex) { @@ -488,9 +538,13 @@ cr_rgb_set_from_hex_str (CRRgb * a_this, const guchar * a_hex) } /** + * cr_rgb_set_from_term: + *@a_this: the instance of #CRRgb to set + *@a_value: the terminal from which to set + * *Set the rgb from a terminal symbol - *@param a_this the instance of #CRRgb to set - *@param a_value the terminal from which to set + * + * Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_rgb_set_from_term (CRRgb *a_this, const struct _CRTerm *a_value) @@ -544,7 +598,7 @@ cr_rgb_set_from_term (CRRgb *a_this, const struct _CRTerm *a_value) } enum CRStatus -cr_rgb_copy (CRRgb *a_dest, CRRgb*a_src) +cr_rgb_copy (CRRgb *a_dest, CRRgb const *a_src) { g_return_val_if_fail (a_dest && a_src, CR_BAD_PARAM_ERROR) ; @@ -554,9 +608,11 @@ cr_rgb_copy (CRRgb *a_dest, CRRgb*a_src) } /** - *Destructor of #CRRgb. - *@param a_this the "this pointer" of the + * cr_rgb_destroy: + *@a_this: the "this pointer" of the *current instance of #CRRgb. + * + *Destructor of #CRRgb. */ void cr_rgb_destroy (CRRgb * a_this) @@ -566,13 +622,16 @@ cr_rgb_destroy (CRRgb * a_this) } /** + * cr_rgb_parse_from_buf: + *@a_str: a string that contains a color description + *@a_enc: the encoding of a_str + * *Parses a text buffer that contains a rgb color * - *@param a_str a string that contains a color description - *@param a_enc the encoding of a_str - *@return the parsed color, or NULL in case of error + *Returns the parsed color, or NULL in case of error */ -CRRgb *cr_rgb_parse_from_buf (const guchar *a_str, +CRRgb * +cr_rgb_parse_from_buf (const guchar *a_str, enum CREncoding a_enc) { enum CRStatus status = CR_OK ; @@ -612,6 +671,4 @@ cleanup: } return result ; } - - diff --git a/src/libcroco/cr-rgb.h b/src/libcroco/cr-rgb.h index 50cec94ec..49d7f7b82 100644 --- a/src/libcroco/cr-rgb.h +++ b/src/libcroco/cr-rgb.h @@ -63,17 +63,17 @@ enum CRStatus cr_rgb_set (CRRgb *a_this, gulong a_red, gulong a_green, gulong a_blue, gboolean a_is_percentage) ; -enum CRStatus cr_rgb_copy (CRRgb *a_dest, CRRgb*a_src) ; +enum CRStatus cr_rgb_copy (CRRgb *a_dest, CRRgb const *a_src) ; enum CRStatus cr_rgb_set_to_inherit (CRRgb *a_this, gboolean a_inherit) ; -gboolean cr_rgb_is_set_to_inherit (CRRgb *a_this) ; +gboolean cr_rgb_is_set_to_inherit (CRRgb const *a_this) ; -gboolean cr_rgb_is_set_to_transparent (CRRgb *a_this) ; +gboolean cr_rgb_is_set_to_transparent (CRRgb const *a_this) ; enum CRStatus cr_rgb_set_to_transparent (CRRgb *a_this, gboolean a_is_transparent) ; -enum CRStatus cr_rgb_set_from_rgb (CRRgb *a_this, CRRgb *a_rgb) ; +enum CRStatus cr_rgb_set_from_rgb (CRRgb *a_this, CRRgb const *a_rgb) ; enum CRStatus cr_rgb_set_from_name (CRRgb *a_this, const guchar *a_color_name) ; @@ -83,9 +83,9 @@ struct _CRTerm; enum CRStatus cr_rgb_set_from_term (CRRgb *a_this, const struct _CRTerm *a_value); -guchar * cr_rgb_to_string (CRRgb *a_this) ; +guchar * cr_rgb_to_string (CRRgb const *a_this) ; -void cr_rgb_dump (CRRgb *a_this, FILE *a_fp) ; +void cr_rgb_dump (CRRgb const *a_this, FILE *a_fp) ; void cr_rgb_destroy (CRRgb *a_this) ; diff --git a/src/libcroco/cr-sel-eng.c b/src/libcroco/cr-sel-eng.c index 266191e82..5bc58a96c 100644 --- a/src/libcroco/cr-sel-eng.c +++ b/src/libcroco/cr-sel-eng.c @@ -26,7 +26,8 @@ #include "cr-node-iface.h" /** - *@file: + *@CRSelEng: + * *The definition of the #CRSelEng class. *The #CRSelEng is actually the "Selection Engine" *class. This is highly experimental for at the moment and @@ -114,6 +115,10 @@ cr_sel_eng_set_node_iface (CRSelEng *const a_this, CRNodeIface const *const a_no PRIVATE(a_this)->node_iface = a_node_iface; } +/* Quick strcmp. Test only for == 0 or != 0, not < 0 or > 0. */ +#define strqcmp(str,lit,lit_len) \ + (strlen (str) != (lit_len) || memcmp (str, lit, lit_len)) + static gboolean lang_pseudo_class_handler (CRSelEng *const a_this, CRAdditionalSel * a_sel, CRXMLNodePtr a_node) @@ -131,7 +136,7 @@ lang_pseudo_class_handler (CRSelEng *const a_this, node_iface = PRIVATE(a_this)->node_iface; - if (strncmp (a_sel->content.pseudo->name->stryng->str, + if (strqcmp (a_sel->content.pseudo->name->stryng->str, "lang", 4) || !a_sel->content.pseudo->type == FUNCTION_PSEUDO) { cr_utils_trace_info ("This handler is for :lang only"); @@ -145,7 +150,7 @@ lang_pseudo_class_handler (CRSelEng *const a_this, for (; node; node = get_next_parent_element_node (node_iface, node)) { char *val = node_iface->getProp (node, "lang"); if (val) { - if (!strncmp (val, + if (!strqcmp (val, a_sel->content.pseudo->extra->stryng->str, a_sel->content.pseudo->extra->stryng->len)) { result = TRUE; @@ -248,6 +253,10 @@ class_add_sel_matches_node (CRAdditionalSel * a_add_sel, if ((cur && !*cur) || cr_utils_is_white_space (*cur) == TRUE) result = TRUE; + } else { /* if it doesn't match, */ + /* then skip to next whitespace character to try again */ + while (cur && *cur && !(cr_utils_is_white_space(*cur) == TRUE)) + cur++; } if (cur && !*cur) break ; @@ -284,7 +293,7 @@ id_add_sel_matches_node (CRAdditionalSel * a_add_sel, id = a_node_iface->getProp (a_node, "id"); if (id) { - if (!strncmp (id, a_add_sel->content.id_name->stryng->str, + if (!strqcmp (id, a_add_sel->content.id_name->stryng->str, a_add_sel->content.id_name->stryng->len)) { result = TRUE; } @@ -1086,8 +1095,10 @@ set_style_from_props (CRStyle * a_style, CRPropList * a_props) ****************************************/ /** + * cr_sel_eng_new: *Creates a new instance of #CRSelEng. - *@return the newly built instance of #CRSelEng of + * + *Returns the newly built instance of #CRSelEng of *NULL if an error occurs. */ CRSelEng * @@ -1122,13 +1133,16 @@ cr_sel_eng_new (void) } /** - *Adds a new handler entry in the handlers entry table. - *@param a_this the current instance of #CRSelEng - *@param a_pseudo_class_sel_name the name of the pseudo class selector. - *@param a_pseudo_class_type the type of the pseudo class selector. - *@param a_handler the actual handler or callback to be called during + * cr_sel_eng_register_pseudo_class_sel_handler: + *@a_this: the current instance of #CRSelEng + *@a_pseudo_class_sel_name: the name of the pseudo class selector. + *@a_pseudo_class_type: the type of the pseudo class selector. + *@a_handler: the actual handler or callback to be called during *the selector evaluation process. - *@return CR_OK, upon successful completion, an error code otherwise. + * + *Adds a new handler entry in the handlers entry table. + * + *Returns CR_OK, upon successful completion, an error code otherwise. */ enum CRStatus cr_sel_eng_register_pseudo_class_sel_handler (CRSelEng * a_this, @@ -1198,10 +1212,13 @@ cr_sel_eng_unregister_pseudo_class_sel_handler (CRSelEng * a_this, } /** + * cr_sel_eng_unregister_all_pseudo_class_sel_handlers: + *@a_this: the current instance of #CRSelEng . + * *Unregisters all the pseudo class sel handlers *and frees all the associated allocated datastructures. - *@param a_this the current instance of #CRSelEng . - *@return CR_OK upon succesful completion, an error code + * + *Returns CR_OK upon succesful completion, an error code *otherwise. */ enum CRStatus @@ -1262,17 +1279,20 @@ cr_sel_eng_get_pseudo_class_selector_handler (CRSelEng * a_this, } /** - *Evaluates a chained list of simple selectors (known as a css2 selector). - *Says wheter if this selector matches the xml node given in parameter or - *not. - *@param a_this the selection engine. - *@param a_sel the simple selector against which the xml node + * cr_sel_eng_matches_node: + *@a_this: the selection engine. + *@a_sel: the simple selector against which the xml node *is going to be matched. - *@param a_node the node against which the selector is going to be matched. - *@param a_result out parameter. The result of the match. Is set to + *@a_node: the node against which the selector is going to be matched. + *@a_result: out parameter. The result of the match. Is set to *TRUE if the selector matches the node, FALSE otherwise. This value *is considered if and only if this functions returns CR_OK. - *@return the CR_OK if the selection ran correctly, an error code otherwise. + * + *Evaluates a chained list of simple selectors (known as a css2 selector). + *Says wheter if this selector matches the xml node given in parameter or + *not. + * + *Returns the CR_OK if the selection ran correctly, an error code otherwise. */ enum CRStatus cr_sel_eng_matches_node (CRSelEng * a_this, CRSimpleSel * a_sel, @@ -1293,20 +1313,22 @@ cr_sel_eng_matches_node (CRSelEng * a_this, CRSimpleSel * a_sel, } /** - *Returns an array of pointers to selectors that matches - *the xml node given in parameter. - * - *@param a_this the current instance of the selection engine. - *@param a_sheet the stylesheet that holds the selectors. - *@param a_node the xml node to consider during the walk thru + * cr_sel_eng_get_matched_rulesets: + *@a_this: the current instance of the selection engine. + *@a_sheet: the stylesheet that holds the selectors. + *@a_node: the xml node to consider during the walk thru *the stylesheet. - *@param a_rulesets out parameter. A pointer to an array of + *@a_rulesets: out parameter. A pointer to an array of *rulesets statement pointers. *a_rulesets is allocated by *this function and must be freed by the caller. However, the caller *must not alter the rulesets statements pointer because they *point to statements that are still in the css stylesheet. - *@param a_len the length of *a_ruleset. - *@return CR_OK upon sucessfull completion, an error code otherwise. + *@a_len: the length of *a_ruleset. + * + *Returns an array of pointers to selectors that matches + *the xml node given in parameter. + * + *Returns CR_OK upon sucessfull completion, an error code otherwise. */ enum CRStatus cr_sel_eng_get_matched_rulesets (CRSelEng * a_this, @@ -1517,8 +1539,10 @@ cr_sel_eng_get_matched_style (CRSelEng * a_this, } /** + * cr_sel_eng_destroy: + *@a_this: the current instance of the selection engine. + * *The destructor of #CRSelEng - *@param a_this the current instance of the selection engine. */ void cr_sel_eng_destroy (CRSelEng * a_this) diff --git a/src/libcroco/cr-selector.c b/src/libcroco/cr-selector.c index d85b3effc..43a3bd914 100644 --- a/src/libcroco/cr-selector.c +++ b/src/libcroco/cr-selector.c @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -25,10 +25,14 @@ #include "cr-parser.h" /** - *Creates a new instance of #CRSelector. - *@param a_simple_sel the initial simple selector list + * cr_selector_new: + * + *@a_simple_sel: the initial simple selector list *of the current instance of #CRSelector. - *@return the newly built instance of #CRSelector, or + * + *Creates a new instance of #CRSelector. + * + *Returns the newly built instance of #CRSelector, or *NULL in case of failure. */ CRSelector * @@ -60,10 +64,14 @@ cr_selector_parse_from_buf (const guchar * a_char_buf, enum CREncoding a_enc) } /** + * cr_selector_append: + * + *@a_this: the current instance of #CRSelector. + *@a_new: the instance of #CRSelector to be appended. + * *Appends a new instance of #CRSelector to the current selector list. - *@param a_this the current instance of #CRSelector. - *@param a_new the instance of #CRSelector to be appended. - *@return the new list. + * + *Returns the new list. */ CRSelector * cr_selector_append (CRSelector * a_this, CRSelector * a_new) @@ -84,10 +92,14 @@ cr_selector_append (CRSelector * a_this, CRSelector * a_new) } /** + * cr_selector_prepend: + * + *@a_this: the current instance of #CRSelector list. + *@a_new: the instance of #CRSelector. + * *Prepends an element to the #CRSelector list. - *@param a_this the current instance of #CRSelector list. - *@param a_new the instance of #CRSelector. - *@return the new list. + * + *Returns the new list. */ CRSelector * cr_selector_prepend (CRSelector * a_this, CRSelector * a_new) @@ -103,10 +115,14 @@ cr_selector_prepend (CRSelector * a_this, CRSelector * a_new) } /** + * cr_selector_append_simple_sel: + * + *@a_this: the current instance of #CRSelector. + *@a_simple_sel: the simple selector to append. + * *append a simple selector to the current #CRSelector list. - *@param a_this the current instance of #CRSelector. - *@param a_simple_sel the simple selector to append. - *@return the new list or NULL in case of failure. + * + *Returns the new list or NULL in case of failure. */ CRSelector * cr_selector_append_simple_sel (CRSelector * a_this, @@ -121,7 +137,7 @@ cr_selector_append_simple_sel (CRSelector * a_this, } guchar * -cr_selector_to_string (CRSelector * a_this) +cr_selector_to_string (CRSelector const * a_this) { guchar *result = NULL; @@ -129,7 +145,7 @@ cr_selector_to_string (CRSelector * a_this) g_return_val_if_fail (str_buf, NULL); if (a_this) { - CRSelector *cur = NULL; + CRSelector const *cur = NULL; for (cur = a_this; cur; cur = cur->next) { if (cur->simple_sel) { @@ -162,12 +178,15 @@ cr_selector_to_string (CRSelector * a_this) } /** + * cr_selector_dump: + * + *@a_this: the current instance of #CRSelector. + *@a_fp: the destination file. + * *Serializes the current instance of #CRSelector to a file. - *@param a_this the current instance of #CRSelector. - *@param a_fp the destination file. */ void -cr_selector_dump (CRSelector * a_this, FILE * a_fp) +cr_selector_dump (CRSelector const * a_this, FILE * a_fp) { guchar *tmp_buf = NULL; @@ -182,9 +201,12 @@ cr_selector_dump (CRSelector * a_this, FILE * a_fp) } /** + * cr_selector_ref: + * + *@a_this: the current instance of #CRSelector. + * *Increments the ref count of the current instance *of #CRSelector. - *@param a_this the current instance of #CRSelector. */ void cr_selector_ref (CRSelector * a_this) @@ -195,12 +217,16 @@ cr_selector_ref (CRSelector * a_this) } /** + * cr_selector_unref: + * + *@a_this: the current instance of #CRSelector. + * *Decrements the ref count of the current instance of *#CRSelector. *If the ref count reaches zero, the current instance of *#CRSelector is destroyed. - *@param a_this the current instance of #CRSelector. - *@return TRUE if this function destroyed the current instance + * + *Returns TRUE if this function destroyed the current instance *of #CRSelector, FALSE otherwise. */ gboolean @@ -221,8 +247,11 @@ cr_selector_unref (CRSelector * a_this) } /** + * cr_selector_destroy: + * + *@a_this: the current instance of #CRSelector. + * *Destroys the selector list. - *@param a_this the current instance of #CRSelector. */ void cr_selector_destroy (CRSelector * a_this) diff --git a/src/libcroco/cr-selector.h b/src/libcroco/cr-selector.h index a22e81fdb..a7e029597 100644 --- a/src/libcroco/cr-selector.h +++ b/src/libcroco/cr-selector.h @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -80,9 +80,9 @@ CRSelector* cr_selector_append_simple_sel (CRSelector *a_this, CRSelector* cr_selector_prepend (CRSelector *a_this, CRSelector *a_new) ; -guchar * cr_selector_to_string (CRSelector *a_this) ; +guchar * cr_selector_to_string (CRSelector const *a_this) ; -void cr_selector_dump (CRSelector *a_this, FILE *a_fp) ; +void cr_selector_dump (CRSelector const *a_this, FILE *a_fp) ; void cr_selector_ref (CRSelector *a_this) ; diff --git a/src/libcroco/cr-simple-sel.c b/src/libcroco/cr-simple-sel.c index 6a51a9526..4f5ac965a 100644 --- a/src/libcroco/cr-simple-sel.c +++ b/src/libcroco/cr-simple-sel.c @@ -26,9 +26,11 @@ #include "cr-simple-sel.h" /** + * cr_simple_sel_new: + * *The constructor of #CRSimpleSel. * - *@return the new instance of #CRSimpleSel. + *Returns the new instance of #CRSimpleSel. */ CRSimpleSel * cr_simple_sel_new (void) @@ -44,11 +46,14 @@ cr_simple_sel_new (void) } /** + * cr_simple_sel_append_simple_sel: + * *Appends a simpe selector to the current list of simple selector. * - *@param a_this the this pointer of the current instance of #CRSimpleSel. - *@param a_sel the simple selector to append. - *@return the new list upon successfull completion, an error code otherwise. + *@a_this: the this pointer of the current instance of #CRSimpleSel. + *@a_sel: the simple selector to append. + * + *Returns: the new list upon successfull completion, an error code otherwise. */ CRSimpleSel * cr_simple_sel_append_simple_sel (CRSimpleSel * a_this, CRSimpleSel * a_sel) @@ -69,10 +74,14 @@ cr_simple_sel_append_simple_sel (CRSimpleSel * a_this, CRSimpleSel * a_sel) } /** + * cr_simple_sel_prepend_simple_sel: + * + *@a_this: the this pointer of the current instance of #CRSimpleSel. + *@a_sel: the simple selector to prepend. + * *Prepends a simple selector to the current list of simple selectors. - *@param a_this the this pointer of the current instance of #CRSimpleSel. - *@param a_sel the simple selector to prepend. - *@return the new list upon successfull completion, an error code otherwise. + * + *Returns the new list upon successfull completion, an error code otherwise. */ CRSimpleSel * cr_simple_sel_prepend_simple_sel (CRSimpleSel * a_this, CRSimpleSel * a_sel) @@ -89,12 +98,12 @@ cr_simple_sel_prepend_simple_sel (CRSimpleSel * a_this, CRSimpleSel * a_sel) } guchar * -cr_simple_sel_to_string (CRSimpleSel * a_this) +cr_simple_sel_to_string (CRSimpleSel const * a_this) { GString *str_buf = NULL; guchar *result = NULL; - CRSimpleSel *cur = NULL; + CRSimpleSel const *cur = NULL; g_return_val_if_fail (a_this, NULL); @@ -150,7 +159,7 @@ cr_simple_sel_to_string (CRSimpleSel * a_this) guchar * -cr_simple_sel_one_to_string (CRSimpleSel * a_this) +cr_simple_sel_one_to_string (CRSimpleSel const * a_this) { GString *str_buf = NULL; guchar *result = NULL; @@ -190,16 +199,18 @@ cr_simple_sel_one_to_string (CRSimpleSel * a_this) } /** + * cr_simple_sel_dump: + *@a_this: the current instance of #CRSimpleSel. + *@a_fp: the destination file pointer. + * *Dumps the selector to a file. *TODO: add the support of unicode in the dump. * - *@param a_this the current instance of #CRSimpleSel. - *@param a_fp the destination file pointer. - *@return CR_OK upon successfull completion, an error code + *Returns CR_OK upon successfull completion, an error code *otherwise. */ enum CRStatus -cr_simple_sel_dump (CRSimpleSel * a_this, FILE * a_fp) +cr_simple_sel_dump (CRSimpleSel const * a_this, FILE * a_fp) { guchar *tmp_str = NULL; @@ -218,16 +229,20 @@ cr_simple_sel_dump (CRSimpleSel * a_this, FILE * a_fp) } /** + * cr_simple_sel_compute_specificity: + * + *@a_this: the current instance of #CRSimpleSel + * *Computes the selector (combinator separated list of simple selectors) *as defined in the css2 spec in chapter 6.4.3 - *@param a_this the current instance of #CRSimpleSel - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successfull completion, an error code otherwise. */ enum CRStatus cr_simple_sel_compute_specificity (CRSimpleSel * a_this) { - CRAdditionalSel *cur_add_sel = NULL; - CRSimpleSel *cur_sel = NULL; + CRAdditionalSel const *cur_add_sel = NULL; + CRSimpleSel const *cur_sel = NULL; gulong a = 0, b = 0, c = 0; @@ -274,10 +289,12 @@ cr_simple_sel_compute_specificity (CRSimpleSel * a_this) } /** + * cr_simple_sel_destroy: + * + *@a_this: the this pointer of the current instance of #CRSimpleSel. + * *The destructor of the current instance of *#CRSimpleSel. Recursively calls the destructor of #CRSimpleSel->next - *@param a_this the this pointer of the current instance of #CRSimpleSel. - * */ void cr_simple_sel_destroy (CRSimpleSel * const a_this) diff --git a/src/libcroco/cr-simple-sel.h b/src/libcroco/cr-simple-sel.h index 29033aff5..d8edc0025 100644 --- a/src/libcroco/cr-simple-sel.h +++ b/src/libcroco/cr-simple-sel.h @@ -40,9 +40,9 @@ G_BEGIN_DECLS enum Combinator { NO_COMBINATOR, - COMB_WS,/*whitesape*/ - COMB_PLUS, - COMB_GT/*greater than*/ + COMB_WS,/*whitespace: descendent*/ + COMB_PLUS,/*'+': preceded by*/ + COMB_GT/*greater than ('>'): child*/ } ; enum SimpleSelectorType @@ -112,13 +112,13 @@ CRSimpleSel * cr_simple_sel_append_simple_sel (CRSimpleSel *a_this, CRSimpleSel * cr_simple_sel_prepend_simple_sel (CRSimpleSel *a_this, CRSimpleSel *a_sel) ; -guchar * cr_simple_sel_to_string (CRSimpleSel *a_this) ; +guchar * cr_simple_sel_to_string (CRSimpleSel const *a_this) ; -guchar * cr_simple_sel_one_to_string (CRSimpleSel * a_this) ; +guchar * cr_simple_sel_one_to_string (CRSimpleSel const * a_this) ; -enum CRStatus cr_simple_sel_dump (CRSimpleSel *a_this, FILE *a_fp) ; +enum CRStatus cr_simple_sel_dump (CRSimpleSel const *a_this, FILE *a_fp) ; -enum CRStatus cr_simple_sel_dump_attr_sel_list (CRSimpleSel *a_this) ; +enum CRStatus cr_simple_sel_dump_attr_sel_list (CRSimpleSel const *a_this) ; enum CRStatus cr_simple_sel_compute_specificity (CRSimpleSel *a_this) ; diff --git a/src/libcroco/cr-statement.c b/src/libcroco/cr-statement.c index 147cc8347..fb8df867f 100644 --- a/src/libcroco/cr-statement.c +++ b/src/libcroco/cr-statement.c @@ -590,14 +590,18 @@ cr_statement_clear (CRStatement * a_this) } /** + * cr_statement_ruleset_to_string: + * + *@a_this: the current instance of #CRStatement + *@a_indent: the number of whitespace to use for indentation + * *Serializes the ruleset statement into a string - *@param a_this the current instance of #CRStatement - *@param a_indent the number of whitespace to use for indentation - *@return the newly allocated serialised string. Must be freed + * + *Returns the newly allocated serialised string. Must be freed *by the caller, using g_free(). */ static gchar * -cr_statement_ruleset_to_string (CRStatement * a_this, glong a_indent) +cr_statement_ruleset_to_string (CRStatement const * a_this, glong a_indent) { gchar *tmp_str = NULL, *result = NULL; @@ -650,15 +654,19 @@ cr_statement_ruleset_to_string (CRStatement * a_this, glong a_indent) /** - *Serializes a font face rule statement into a string. - *@param a_this the current instance of #CRStatement to consider + * cr_statement_font_face_rule_to_string: + * + *@a_this: the current instance of #CRStatement to consider *It must be a font face rule statement. - *@param a_indent the number of white spaces of indentation. - *@return the serialized string. Must be deallocated by the caller + *@a_indent: the number of white spaces of indentation. + * + *Serializes a font face rule statement into a string. + * + *Returns the serialized string. Must be deallocated by the caller *using g_free(). */ static gchar * -cr_statement_font_face_rule_to_string (CRStatement * a_this, +cr_statement_font_face_rule_to_string (CRStatement const * a_this, glong a_indent) { gchar *result = NULL, *tmp_str = NULL ; @@ -696,13 +704,17 @@ cr_statement_font_face_rule_to_string (CRStatement * a_this, /** - *Serialises an @charset statement into a string. - *@param a_this the statement to serialize. - *@return the serialized charset statement. Must be + * cr_statement_charset_to_string: + * + *Serialises an \@charset statement into a string. + *@a_this: the statement to serialize. + *@a_indent: the number of indentation spaces + * + *Returns the serialized charset statement. Must be *freed by the caller using g_free(). */ static gchar * -cr_statement_charset_to_string (CRStatement *a_this, +cr_statement_charset_to_string (CRStatement const *a_this, gulong a_indent) { gchar *str = NULL ; @@ -738,13 +750,16 @@ cr_statement_charset_to_string (CRStatement *a_this, /** + * cr_statement_at_page_rule_to_string: + * *Serialises the at page rule statement into a string - *@param a_this the current instance of #CRStatement. Must - *be an "@page" rule statement. - *@return the serialized string. Must be freed by the caller + *@a_this: the current instance of #CRStatement. Must + *be an "\@page" rule statement. + * + *Returns the serialized string. Must be freed by the caller */ static gchar * -cr_statement_at_page_rule_to_string (CRStatement *a_this, +cr_statement_at_page_rule_to_string (CRStatement const *a_this, gulong a_indent) { gchar *result = NULL ; @@ -788,19 +803,19 @@ cr_statement_at_page_rule_to_string (CRStatement *a_this, /** - *Serializes an @media statement. + *Serializes an \@media statement. *@param a_this the current instance of #CRStatement *@param a_indent the number of spaces of indentation. - *@return the serialized @media statement. Must be freed + *@return the serialized \@media statement. Must be freed *by the caller using g_free(). */ static gchar * -cr_statement_media_rule_to_string (CRStatement *a_this, +cr_statement_media_rule_to_string (CRStatement const *a_this, gulong a_indent) { gchar *str = NULL ; GString *stringue = NULL ; - GList *cur = NULL; + GList const *cur = NULL; g_return_val_if_fail (a_this->type == AT_MEDIA_RULE_STMT, NULL); @@ -814,7 +829,7 @@ cr_statement_media_rule_to_string (CRStatement *a_this, cur = cur->next) { if (cur->data) { gchar *str = cr_string_dup2 - ((CRString *) cur->data); + ((CRString const *) cur->data); if (str) { if (cur->prev) { @@ -850,7 +865,7 @@ cr_statement_media_rule_to_string (CRStatement *a_this, static gchar * -cr_statement_import_rule_to_string (CRStatement *a_this, +cr_statement_import_rule_to_string (CRStatement const *a_this, gulong a_indent) { GString *stringue = NULL ; @@ -878,12 +893,12 @@ cr_statement_import_rule_to_string (CRStatement *a_this, return NULL; if (a_this->kind.import_rule->media_list) { - GList *cur = NULL; + GList const *cur = NULL; for (cur = a_this->kind.import_rule->media_list; cur; cur = cur->next) { if (cur->data) { - CRString *crstr = (CRString *)cur->data; + CRString const *crstr = cur->data; if (cur->prev) { g_string_append @@ -916,12 +931,16 @@ cr_statement_import_rule_to_string (CRStatement *a_this, ******************/ /** + * cr_statement_does_buf_parses_against_core: + * + *@a_buf: the buffer to parse. + *@a_encoding: the character encoding of a_buf. + * *Tries to parse a buffer and says whether if the content of the buffer *is a css statement as defined by the "Core CSS Grammar" (chapter 4 of the *css spec) or not. - *@param a_buf the buffer to parse. - *@param a_encoding the character encoding of a_buf. - *@return TRUE if the buffer parses against the core grammar, false otherwise. + * + *Returns TRUE if the buffer parses against the core grammar, false otherwise. */ gboolean cr_statement_does_buf_parses_against_core (const guchar * a_buf, @@ -955,13 +974,17 @@ cr_statement_does_buf_parses_against_core (const guchar * a_buf, } /** + * cr_statement_parse_from_buf: + * + *@a_buf: the buffer to parse. + *@a_encoding: the character encoding of a_buf. + * *Parses a buffer that contains a css statement and returns - *an instance of #CRStatement in case of successfull parsing. - *TODO: at support of "@import" rules. - *@param a_buf the buffer to parse. - *@param a_encoding the character encoding of a_buf. - *@return the newly built instance of #CRStatement in case - *of successfull parsing, NULL otherwise. + *an instance of #CRStatement in case of successful parsing. + *TODO: at support of "\@import" rules. + * + *Returns the newly built instance of #CRStatement in case + *of successful parsing, NULL otherwise. */ CRStatement * cr_statement_parse_from_buf (const guchar * a_buf, enum CREncoding a_encoding) @@ -970,7 +993,7 @@ cr_statement_parse_from_buf (const guchar * a_buf, enum CREncoding a_encoding) /* *The strategy of this function is "brute force". - *It tries to parse all the types of #CRStatement it knows about. + *It tries to parse all the types of CRStatement it knows about. *I could do this a smarter way but I don't have the time now. *I think I will revisit this when time of performances and *pull based incremental parsing comes. @@ -1025,11 +1048,15 @@ cr_statement_parse_from_buf (const guchar * a_buf, enum CREncoding a_encoding) } /** + * cr_statement_ruleset_parse_from_buf: + * + *@a_buf: the buffer to parse. + *@a_enc: the character encoding of a_buf. + * *Parses a buffer that contains a ruleset statement and instanciates *a #CRStatement of type RULESET_STMT. - *@param a_buf the buffer to parse. - *@param a_enc the character encoding of a_buf. - *@param the newly built instance of #CRStatement in case of successful parsing, + * + *Returns the newly built instance of #CRStatement in case of successful parsing, *NULL otherwise. */ CRStatement * @@ -1090,15 +1117,19 @@ cr_statement_ruleset_parse_from_buf (const guchar * a_buf, } /** - *Creates a new instance of #CRStatement of type - *#CRRulSet. - *@param a_sel_list the list of #CRSimpleSel (selectors) + * cr_statement_new_ruleset: + * + *@a_sel_list: the list of #CRSimpleSel (selectors) *the rule applies to. - *@param a_decl_list the list of instances of #CRDeclaration + *@a_decl_list: the list of instances of #CRDeclaration *that composes the ruleset. - *@param a_media_types a list of instances of GString that + *@a_media_types: a list of instances of GString that *describe the media list this ruleset applies to. - *@return the new instance of #CRStatement or NULL if something + * + *Creates a new instance of #CRStatement of type + *#CRRulSet. + * + *Returns the new instance of #CRStatement or NULL if something *went wrong. */ CRStatement * @@ -1155,11 +1186,15 @@ cr_statement_new_ruleset (CRStyleSheet * a_sheet, } /** - *Parses a buffer that contains an "@media" declaration - *and builds an @media css statement. - *@param a_buf the input to parse. - *@param a_enc the encoding of the buffer. - *@return the @media statement, or NULL if the buffer could not + * cr_statement_at_media_rule_parse_from_buf: + * + *@a_buf: the input to parse. + *@a_enc: the encoding of the buffer. + * + *Parses a buffer that contains an "\@media" declaration + *and builds an \@media css statement. + * + *Returns the \@media statement, or NULL if the buffer could not *be successfully parsed. */ CRStatement * @@ -1229,11 +1264,15 @@ cr_statement_at_media_rule_parse_from_buf (const guchar * a_buf, } /** + * cr_statement_new_at_media_rule: + * + *@a_ruleset: the ruleset statements contained + *in the \@media rule. + *@a_media: the media string list. A list of GString pointers. + * *Instanciates an instance of #CRStatement of type - *AT_MEDIA_RULE_STMT (@media ruleset). - *@param a_ruleset the ruleset statements contained - *in the @media rule. - *@param a_media, the media string list. A list of GString pointers. + *AT_MEDIA_RULE_STMT (\@media ruleset). + * */ CRStatement * cr_statement_new_at_media_rule (CRStyleSheet * a_sheet, @@ -1284,12 +1323,16 @@ cr_statement_new_at_media_rule (CRStyleSheet * a_sheet, } /** + * cr_statement_new_at_import_rule: + * + *@a_url: the url to connect to the get the file + *to be imported. + *@a_sheet: the imported parsed stylesheet. + * *Creates a new instance of #CRStatment of type *#CRAtImportRule. - *@param a_url the url to connect to the get the file - *to be imported. - *@param a_sheet the imported parsed stylesheet. - *@return the newly built instance of #CRStatement. + * + *Returns the newly built instance of #CRStatement. */ CRStatement * cr_statement_new_at_import_rule (CRStyleSheet * a_container_sheet, @@ -1326,12 +1369,16 @@ cr_statement_new_at_import_rule (CRStyleSheet * a_container_sheet, } /** - *Parses a buffer that contains an "@import" rule and + * cr_statement_at_import_rule_parse_from_buf: + * + *@a_buf: the buffer to parse. + *@a_encoding: the encoding of a_buf. + * + *Parses a buffer that contains an "\@import" rule and *instanciate a #CRStatement of type AT_IMPORT_RULE_STMT - *@param a_buf the buffer to parse. - *@param a_encoding the encoding of a_buf. - *@return the newly built instance of #CRStatement in case of - *a successfull parsing, NULL otherwise. + * + *Returns the newly built instance of #CRStatement in case of + *a successful parsing, NULL otherwise. */ CRStatement * cr_statement_at_import_rule_parse_from_buf (const guchar * a_buf, @@ -1398,13 +1445,17 @@ cr_statement_at_import_rule_parse_from_buf (const guchar * a_buf, } /** - *Creates a new instance of #CRStatement of type - *#CRAtPageRule. - *@param a_decl_list a list of instances of #CRDeclarations + * cr_statement_new_at_page_rule: + * + *@a_decl_list: a list of instances of #CRDeclarations *which is actually the list of declarations that applies to *this page rule. - *@param a_selector the page rule selector. - *@return the newly built instance of #CRStatement or NULL + *@a_selector: the page rule selector. + * + *Creates a new instance of #CRStatement of type + *#CRAtPageRule. + * + *Returns the newly built instance of #CRStatement or NULL *in case of error. */ CRStatement * @@ -1444,11 +1495,15 @@ cr_statement_new_at_page_rule (CRStyleSheet * a_sheet, } /** - *Parses a buffer that contains an "@page" production and, + * cr_statement_at_page_rule_parse_from_buf: + * + *@a_buf: the character buffer to parse. + *@a_encoding: the character encoding of a_buf. + * + *Parses a buffer that contains an "\@page" production and, *if the parsing succeeds, builds the page statement. - *@param a_buf the character buffer to parse. - *@param a_encoding the character encoding of a_buf. - *@return the newly built at page statement in case of successfull parsing, + * + *Returns the newly built at page statement in case of successful parsing, *NULL otherwise. */ CRStatement * @@ -1513,12 +1568,16 @@ cr_statement_at_page_rule_parse_from_buf (const guchar * a_buf, } /** - *Creates a new instance of #CRStatement of type - *#CRAtCharsetRule. - *@param a_charset the string representing the charset. + * cr_statement_new_at_charset_rule: + * + *@a_charset: the string representing the charset. *Note that the newly built instance of #CRStatement becomes *the owner of a_charset. The caller must not free a_charset !!!. - *@return the newly built instance of #CRStatement or NULL + * + *Creates a new instance of #CRStatement of type + *#CRAtCharsetRule. + * + *Returns the newly built instance of #CRStatement or NULL *if an error arises. */ CRStatement * @@ -1552,11 +1611,15 @@ cr_statement_new_at_charset_rule (CRStyleSheet * a_sheet, } /** - *Parses a buffer that contains an '@charset' rule and + * cr_statement_at_charset_rule_parse_from_buf: + * + *@a_buf: the buffer to parse. + *@a_encoding: the character encoding of the buffer. + * + *Parses a buffer that contains an '\@charset' rule and *creates an instance of #CRStatement of type AT_CHARSET_RULE_STMT. - *@param a_buf the buffer to parse. - *@param the character encoding of the buffer. - *@return the newly built instance of #CRStatement. + * + *Returns the newly built instance of #CRStatement. */ CRStatement * cr_statement_at_charset_rule_parse_from_buf (const guchar * a_buf, @@ -1602,10 +1665,14 @@ cr_statement_at_charset_rule_parse_from_buf (const guchar * a_buf, } /** - *Creates an instance of #CRStatement of type #CRAtFontFaceRule. - *@param a_font_decls a list of instances of #CRDeclaration. Each declaration + * cr_statement_new_at_font_face_rule: + * + *@a_font_decls: a list of instances of #CRDeclaration. Each declaration *is actually a font declaration. - *@return the newly built instance of #CRStatement. + * + *Creates an instance of #CRStatement of type #CRAtFontFaceRule. + * + *Returns the newly built instance of #CRStatement. */ CRStatement * cr_statement_new_at_font_face_rule (CRStyleSheet * a_sheet, @@ -1638,11 +1705,16 @@ cr_statement_new_at_font_face_rule (CRStyleSheet * a_sheet, } /** - *Parses a buffer that contains an "@font-face" rule and builds + * cr_statement_font_face_rule_parse_from_buf: + * + * + *@a_buf: the buffer to parse. + *@a_encoding: the character encoding of a_buf. + * + *Parses a buffer that contains an "\@font-face" rule and builds *an instance of #CRStatement of type AT_FONT_FACE_RULE_STMT out of it. - *@param a_buf the buffer to parse. - *@param a_encoding the character encoding of a_buf. - *@return the newly built instance of #CRStatement in case of successufull + * + *Returns the newly built instance of #CRStatement in case of successufull *parsing, NULL otherwise. */ CRStatement * @@ -1710,10 +1782,14 @@ cr_statement_font_face_rule_parse_from_buf (const guchar * a_buf, } /** + * cr_statement_set_parent_sheet: + * + *@a_this: the current instance of #CRStatement. + *@a_sheet: the sheet that contains the current statement. + * *Sets the container stylesheet. - *@param a_this the current instance of #CRStatement. - *@param a_sheet the sheet that contains the current statement. - *@return CR_OK upon successfull completion, an errror code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_set_parent_sheet (CRStatement * a_this, CRStyleSheet * a_sheet) @@ -1724,10 +1800,14 @@ cr_statement_set_parent_sheet (CRStatement * a_this, CRStyleSheet * a_sheet) } /** + * cr_statement_get_parent_sheet: + * + *@a_this: the current #CRStatement. + *@a_sheet: out parameter. A pointer to the sheets that + * *Gets the sheets that contains the current statement. - *@param a_this the current #CRStatement. - *@param a_sheet out parameter. A pointer to the sheets that - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_get_parent_sheet (CRStatement * a_this, CRStyleSheet ** a_sheet) @@ -1738,10 +1818,14 @@ cr_statement_get_parent_sheet (CRStatement * a_this, CRStyleSheet ** a_sheet) } /** + * cr_statement_append: + * + *@a_this: the current instance of the statement list. + *@a_new: a_new the new instance of #CRStatement to append. + * *Appends a new statement to the statement list. - *@param a_this the current instance of the statement list. - *@param a_this a_new the new instance of #CRStatement to append. - *@return the new list statement list, or NULL in cas of failure. + * + *Returns the new list statement list, or NULL in cas of failure. */ CRStatement * cr_statement_append (CRStatement * a_this, CRStatement * a_new) @@ -1764,11 +1848,15 @@ cr_statement_append (CRStatement * a_this, CRStatement * a_new) } /** + * cr_statement_prepend: + * + *@a_this: the current instance of #CRStatement. + *@a_new: the new statement to prepend. + * *Prepends the an instance of #CRStatement to *the current statement list. - *@param a_this the current instance of #CRStatement. - *@param a_new the new statement to prepend. - *@return the new list with the new statement prepended, + * + *Returns the new list with the new statement prepended, *or NULL in case of an error. */ CRStatement * @@ -1791,10 +1879,14 @@ cr_statement_prepend (CRStatement * a_this, CRStatement * a_new) } /** + * cr_statement_unlink: + * + *@a_this: the current statements list. + *@a_to_unlink: the statement to unlink from the list. + * *Unlinks a statement from the statements list. - *@param a_this the current statements list. - *@param a_to_unlink the statement to unlink from the list. - *@return the new list where a_to_unlink has been unlinked + * + *Returns the new list where a_to_unlink has been unlinked *from, or NULL in case of error. */ CRStatement * @@ -1838,14 +1930,18 @@ cr_statement_unlink (CRStatement * a_stmt) } /** - *Return the number of rules in the statement list; - *@param a_this the current instance of #CRStatement. - *@return number of rules in the statement list. + * cr_statement_nr_rules: + * + *@a_this: the current instance of #CRStatement. + * + *Gets the number of rules in the statement list; + * + *Returns number of rules in the statement list. */ gint -cr_statement_nr_rules (CRStatement * a_this) +cr_statement_nr_rules (CRStatement const * a_this) { - CRStatement *cur = NULL; + CRStatement const *cur = NULL; int nr = 0; g_return_val_if_fail (a_this, -1); @@ -1856,10 +1952,14 @@ cr_statement_nr_rules (CRStatement * a_this) } /** + * cr_statement_get_from_list: + * + *@a_this: the current instance of #CRStatement. + *@itemnr: the index into the statement list. + * *Use an index to get a CRStatement from the statement list. - *@param a_this the current instance of #CRStatement. - *@param itemnr the index into the statement list. - *@return CRStatement at position itemnr, if itemnr > number of statements - 1, + * + *Returns CRStatement at position itemnr, if itemnr > number of statements - 1, *it will return NULL. */ CRStatement * @@ -1877,13 +1977,17 @@ cr_statement_get_from_list (CRStatement * a_this, int itemnr) } /** - *Sets a selector list to a ruleset statement. - *@param a_this the current ruleset statement. - *@param a_sel_list the selector list to set. Note + * cr_statement_ruleset_set_sel_list: + * + *@a_this: the current ruleset statement. + *@a_sel_list: the selector list to set. Note *that this function increments the ref count of a_sel_list. *The sel list will be destroyed at the destruction of the *current instance of #CRStatement. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Sets a selector list to a ruleset statement. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_ruleset_set_sel_list (CRStatement * a_this, @@ -1904,12 +2008,16 @@ cr_statement_ruleset_set_sel_list (CRStatement * a_this, } /** + * cr_statement_ruleset_get_declarations: + * + *@a_this: the current instance of #CRStatement. + *@a_decl_list: out parameter. A pointer to the the returned + *list of declaration. Must not be NULL. + * *Gets a pointer to the list of declaration contained *in the ruleset statement. - *@param a_this the current instance of #CRStatement. - *@a_decl_list out parameter. A pointer to the returned - *list of declaration. Must not be NULL. - *@return CR_OK upon successfull completion, an error code if something + * + *Returns CR_OK upon successful completion, an error code if something *bad happened. */ enum CRStatus @@ -1927,15 +2035,19 @@ cr_statement_ruleset_get_declarations (CRStatement * a_this, } /** + * cr_statement_ruleset_get_sel_list: + * + *@a_this: the current ruleset statement. + *@a_list: out parameter. The returned selector list, + *if and only if the function returned CR_OK. + * *Gets a pointer to the selector list contained in *the current ruleset statement. - *@param a_this the current ruleset statement. - *@param a_list out parameter. The returned selector list, - *if and only if the function returned CR_OK. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_statement_ruleset_get_sel_list (CRStatement * a_this, CRSelector ** a_list) +cr_statement_ruleset_get_sel_list (CRStatement const * a_this, CRSelector ** a_list) { g_return_val_if_fail (a_this && a_this->type == RULESET_STMT && a_this->kind.ruleset, CR_BAD_PARAM_ERROR); @@ -1946,11 +2058,15 @@ cr_statement_ruleset_get_sel_list (CRStatement * a_this, CRSelector ** a_list) } /** - *Sets a declaration list to the current ruleset statement. - *@param a_this the current ruleset statement. - *@param a_list the declaration list to be added to the current + * cr_statement_ruleset_set_decl_list: + * + *@a_this: the current ruleset statement. + *@a_list: the declaration list to be added to the current *ruleset statement. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Sets a declaration list to the current ruleset statement. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_ruleset_set_decl_list (CRStatement * a_this, @@ -1972,11 +2088,15 @@ cr_statement_ruleset_set_decl_list (CRStatement * a_this, } /** + * cr_statement_ruleset_append_decl2: + * + *@a_this: the current statement. + *@a_prop: the property of the declaration. + *@a_value: the value of the declaration. + * *Appends a declaration to the current ruleset statement. - *@param a_this the current statement. - *@param a_prop the property of the declaration. - *@param a_value the value of the declaration. - *@return CR_OK uppon successfull completion, an error code + * + *Returns CR_OK upon successful completion, an error code *otherwise. */ enum CRStatus @@ -1999,10 +2119,14 @@ cr_statement_ruleset_append_decl2 (CRStatement * a_this, } /** + * cr_statement_ruleset_append_decl: + * *Appends a declaration to the current statement. - *@param a_this the current statement. - *@param a_declaration the declaration to append. - *@return CR_OK upon sucessfull completion, an error code + * + *@a_this: the current statement. + *@a_declaration: the declaration to append. + * + *Returns CR_OK upon sucessful completion, an error code *otherwise. */ enum CRStatus @@ -2023,13 +2147,16 @@ cr_statement_ruleset_append_decl (CRStatement * a_this, } /** - *Sets a stylesheet to the current @import rule. - *@param a_this the current @import rule. - *@param a_sheet the stylesheet. The stylesheet is owned + * cr_statement_at_import_rule_set_imported_sheet: + * + *Sets a stylesheet to the current \@import rule. + *@a_this: the current \@import rule. + *@a_sheet: the stylesheet. The stylesheet is owned *by the current instance of #CRStatement, that is, the *stylesheet will be destroyed when the current instance - *of #CRStatement will be destroyed. - *@return CR_OK upon successfull completion, an error code otherwise. + *of #CRStatement is destroyed. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_import_rule_set_imported_sheet (CRStatement * a_this, @@ -2046,11 +2173,14 @@ cr_statement_at_import_rule_set_imported_sheet (CRStatement * a_this, } /** - *Gets the stylesheet contained by the @import rule statement. - *@param a_this the current @import rule statement. - *@param a_sheet out parameter. The returned stylesheet if and + * cr_statement_at_import_rule_get_imported_sheet: + * + *@a_this: the current \@import rule statement. + *@a_sheet: out parameter. The returned stylesheet if and *only if the function returns CR_OK. - *@return CR_OK upon sucessfull completion, an error code otherwise. + * + *Gets the stylesheet contained by the \@import rule statement. + *Returns CR_OK upon sucessful completion, an error code otherwise. */ enum CRStatus cr_statement_at_import_rule_get_imported_sheet (CRStatement * a_this, @@ -2066,10 +2196,14 @@ cr_statement_at_import_rule_get_imported_sheet (CRStatement * a_this, } /** - *Sets an url to the current @import rule statement. - *@param a_this the current @import rule statement. - *@param a_url the url to set. - *@return CR_OK upon successfull completion, an error code otherwise. + * cr_statement_at_import_rule_set_url: + * + *@a_this: the current \@import rule statement. + *@a_url: the url to set. + * + *Sets an url to the current \@import rule statement. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_import_rule_set_url (CRStatement * a_this, @@ -2090,13 +2224,17 @@ cr_statement_at_import_rule_set_url (CRStatement * a_this, } /** - *Gets the url of the @import rule statement. - *@param the current @import rule statement. - *@param a_url out parameter. The returned url if + * cr_statement_at_import_rule_get_url: + * + *@a_this: the current \@import rule statement. + *@a_url: out parameter. The returned url if *and only if the function returned CR_OK. + * + *Gets the url of the \@import rule statement. + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_statement_at_import_rule_get_url (CRStatement * a_this, +cr_statement_at_import_rule_get_url (CRStatement const * a_this, CRString ** a_url) { g_return_val_if_fail (a_this @@ -2110,12 +2248,14 @@ cr_statement_at_import_rule_get_url (CRStatement * a_this, } /** - *Return the number of rules in the media rule; - *@param a_this the current instance of #CRStatement. - *@return number of rules in the media rule. + * cr_statement_at_media_nr_rules: + * + *@a_this: the current instance of #CRStatement. + * + *Returns the number of rules in the media rule; */ int -cr_statement_at_media_nr_rules (CRStatement * a_this) +cr_statement_at_media_nr_rules (CRStatement const * a_this) { g_return_val_if_fail (a_this && a_this->type == AT_MEDIA_RULE_STMT @@ -2125,10 +2265,14 @@ cr_statement_at_media_nr_rules (CRStatement * a_this) } /** + * cr_statement_at_media_get_from_list: + * + *@a_this: the current instance of #CRStatement. + *@itemnr: the index into the media rule list of rules. + * *Use an index to get a CRStatement from the media rule list of rules. - *@param a_this the current instance of #CRStatement. - *@param itemnr the index into the media rule list of rules. - *@return CRStatement at position itemnr, if itemnr > number of rules - 1, + * + *Returns CRStatement at position itemnr, if itemnr > number of rules - 1, *it will return NULL. */ CRStatement * @@ -2143,11 +2287,15 @@ cr_statement_at_media_get_from_list (CRStatement * a_this, int itemnr) } /** - *Sets a declaration list to the current @page rule statement. - *@param a_this the current @page rule statement. - *@param a_decl_list the declaration list to add. Will be freed + * cr_statement_at_page_rule_set_declarations: + * + *@a_this: the current \@page rule statement. + *@a_decl_list: the declaration list to add. Will be freed *by the current instance of #CRStatement when it is destroyed. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Sets a declaration list to the current \@page rule statement. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_page_rule_set_declarations (CRStatement * a_this, @@ -2171,11 +2319,15 @@ cr_statement_at_page_rule_set_declarations (CRStatement * a_this, } /** - *Gets the declaration list associated to the current @page rule + * cr_statement_at_page_rule_get_declarations: + * + *@a_this: the current \@page rule statement. + *@a_decl_list: out parameter. The returned declaration list. + * + *Gets the declaration list associated to the current \@page rule *statement. - *@param a_this the current @page rule statement. - *@param a_decl_list out parameter. The returned declaration list. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_page_rule_get_declarations (CRStatement * a_this, @@ -2191,10 +2343,15 @@ cr_statement_at_page_rule_get_declarations (CRStatement * a_this, } /** - *Sets the charset of the current @charset rule statement. - *@param a_this the current @charset rule statement. - *@param a_charset the charset to set. - *@return CR_OK upon successfull completion, an error code otherwise. + * cr_statement_at_charset_rule_set_charset: + * + * + *@a_this: the current \@charset rule statement. + *@a_charset: the charset to set. + * + *Sets the charset of the current \@charset rule statement. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_charset_rule_set_charset (CRStatement * a_this, @@ -2213,14 +2370,18 @@ cr_statement_at_charset_rule_set_charset (CRStatement * a_this, } /** - *Gets the charset string associated to the current - *@charset rule statement. - *@param a_this the current @charset rule statement. - *@param a_charset out parameter. The returned charset string if + * cr_statement_at_charset_rule_get_charset: + *@a_this: the current \@charset rule statement. + *@a_charset: out parameter. The returned charset string if *and only if the function returned CR_OK. + * + *Gets the charset string associated to the current + *\@charset rule statement. + * + * Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus -cr_statement_at_charset_rule_get_charset (CRStatement * a_this, +cr_statement_at_charset_rule_get_charset (CRStatement const * a_this, CRString ** a_charset) { g_return_val_if_fail (a_this @@ -2234,10 +2395,14 @@ cr_statement_at_charset_rule_get_charset (CRStatement * a_this, } /** - *Sets a declaration list to the current @font-face rule statement. - *@param a_this the current @font-face rule statement. - *@param a_decls the declarations list to set. - *@return CR_OK upon successfull completion, an error code otherwise. + * cr_statement_at_font_face_rule_set_decls: + * + *@a_this: the current \@font-face rule statement. + *@a_decls: the declarations list to set. + * + *Sets a declaration list to the current \@font-face rule statement. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_font_face_rule_set_decls (CRStatement * a_this, @@ -2259,12 +2424,16 @@ cr_statement_at_font_face_rule_set_decls (CRStatement * a_this, } /** - *Gets the declaration list associated to the current instance - *of @font-face rule statement. - *@param a_this the current @font-face rule statement. - *@param a_decls out parameter. The returned declaration list if + * cr_statement_at_font_face_rule_get_decls: + * + *@a_this: the current \@font-face rule statement. + *@a_decls: out parameter. The returned declaration list if *and only if this function returns CR_OK. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Gets the declaration list associated to the current instance + *of \@font-face rule statement. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_font_face_rule_get_decls (CRStatement * a_this, @@ -2281,12 +2450,16 @@ cr_statement_at_font_face_rule_get_decls (CRStatement * a_this, } /** - *Adds a declaration to the current @font-face rule + * cr_statement_at_font_face_rule_add_decl: + * + *@a_this: the current \@font-face rule statement. + *@a_prop: the property of the declaration. + *@a_value: the value of the declaration. + * + *Adds a declaration to the current \@font-face rule *statement. - *@param a_this the current @font-face rule statement. - *@param a_prop the property of the declaration. - *@param a_value the value of the declaration. - *@return CR_OK upon successfull completion, an error code otherwise. + * + *Returns CR_OK upon successful completion, an error code otherwise. */ enum CRStatus cr_statement_at_font_face_rule_add_decl (CRStatement * a_this, @@ -2313,15 +2486,20 @@ cr_statement_at_font_face_rule_add_decl (CRStatement * a_this, return CR_OK; } + /** + * cr_statement_to_string: + * + *@a_this: the current statement to serialize + *@a_indent: the number of white space of indentation. + * *Serializes a css statement into a string - *@param a_this the current statement to serialize - *@param a_indent the number of white space of indentation. - *@return the serialized statement. Must be freed by the caller + * + *Returns the serialized statement. Must be freed by the caller *using g_free(). */ gchar * -cr_statement_to_string (CRStatement * a_this, gulong a_indent) +cr_statement_to_string (CRStatement const * a_this, gulong a_indent) { gchar *str = NULL ; @@ -2367,9 +2545,9 @@ cr_statement_to_string (CRStatement * a_this, gulong a_indent) } gchar* -cr_statement_list_to_string (CRStatement *a_this, gulong a_indent) +cr_statement_list_to_string (CRStatement const *a_this, gulong a_indent) { - CRStatement *cur_stmt = NULL ; + CRStatement const *cur_stmt = NULL ; GString *stringue = NULL ; gchar *str = NULL ; @@ -2400,13 +2578,16 @@ cr_statement_list_to_string (CRStatement *a_this, gulong a_indent) } /** + * cr_statement_dump: + * + *@a_this: the current css2 statement. + *@a_fp: the destination file pointer. + *@a_indent: the number of white space indentation characters. + * *Dumps the css2 statement to a file. - *@param a_this the current css2 statement. - *@param a_fp the destination file pointer. - *@param a_indent the number of white space indentation characters. */ void -cr_statement_dump (CRStatement * a_this, FILE * a_fp, gulong a_indent) +cr_statement_dump (CRStatement const * a_this, FILE * a_fp, gulong a_indent) { gchar *str = NULL ; @@ -2422,13 +2603,16 @@ cr_statement_dump (CRStatement * a_this, FILE * a_fp, gulong a_indent) } /** + * cr_statement_dump_ruleset: + * + *@a_this: the current instance of #CRStatement. + *@a_fp: the destination file pointer. + *@a_indent: the number of indentation white spaces to add. + * *Dumps a ruleset statement to a file. - *@param a_this the current instance of #CRStatement. - *@param a_fp the destination file pointer. - *@param a_indent the number of indentation white spaces to add. */ void -cr_statement_dump_ruleset (CRStatement * a_this, FILE * a_fp, glong a_indent) +cr_statement_dump_ruleset (CRStatement const * a_this, FILE * a_fp, glong a_indent) { g_return_if_fail (a_fp && a_this); gchar *str = cr_statement_ruleset_to_string (a_this, a_indent); @@ -2440,13 +2624,16 @@ cr_statement_dump_ruleset (CRStatement * a_this, FILE * a_fp, glong a_indent) } /** + * cr_statement_dump_font_face_rule: + * + *@a_this: the current instance of font face rule statement. + *@a_fp: the destination file pointer. + *@a_indent: the number of white space indentation. + * *Dumps a font face rule statement to a file. - *@param a_this the current instance of font face rule statement. - *@param a_fp the destination file pointer. - *@param a_indent the number of white space indentation. */ void -cr_statement_dump_font_face_rule (CRStatement * a_this, FILE * a_fp, +cr_statement_dump_font_face_rule (CRStatement const * a_this, FILE * a_fp, glong a_indent) { gchar *str = NULL ; @@ -2463,13 +2650,16 @@ cr_statement_dump_font_face_rule (CRStatement * a_this, FILE * a_fp, } /** - *Dumps an @charset rule statement to a file. - *@param a_this the current instance of the @charset rule statement. - *@param a_fp the destination file pointer. - *@param a_indent the number of indentation white spaces. + * cr_statement_dump_charset: + * + *@a_this: the current instance of the \@charset rule statement. + *@a_fp: the destination file pointer. + *@a_indent: the number of indentation white spaces. + * + *Dumps an \@charset rule statement to a file. */ void -cr_statement_dump_charset (CRStatement * a_this, FILE * a_fp, gulong a_indent) +cr_statement_dump_charset (CRStatement const * a_this, FILE * a_fp, gulong a_indent) { g_return_if_fail (a_this && a_this->type == AT_CHARSET_RULE_STMT); @@ -2484,13 +2674,16 @@ cr_statement_dump_charset (CRStatement * a_this, FILE * a_fp, gulong a_indent) /** - *Dumps an @page rule statement on stdout. - *@param a_this the statement to dump on stdout. - *@param a_fp the destination file pointer. - *@param a_indent the number of indentation white spaces. + * cr_statement_dump_page: + * + *@a_this: the statement to dump on stdout. + *@a_fp: the destination file pointer. + *@a_indent: the number of indentation white spaces. + * + *Dumps an \@page rule statement on stdout. */ void -cr_statement_dump_page (CRStatement * a_this, FILE * a_fp, gulong a_indent) +cr_statement_dump_page (CRStatement const * a_this, FILE * a_fp, gulong a_indent) { g_return_if_fail (a_this && a_this->type == AT_PAGE_RULE_STMT @@ -2506,13 +2699,16 @@ cr_statement_dump_page (CRStatement * a_this, FILE * a_fp, gulong a_indent) /** - *Dumps an @media rule statement to a file. - *@param a_this the statement to dump. - *@param a_fp the destination file pointer - *@param a_indent the number of white spaces indentation. + * cr_statement_dump_media_rule: + * + *@a_this: the statement to dump. + *@a_fp: the destination file pointer + *@a_indent: the number of white spaces indentation. + * + *Dumps an \@media rule statement to a file. */ void -cr_statement_dump_media_rule (CRStatement * a_this, +cr_statement_dump_media_rule (CRStatement const * a_this, FILE * a_fp, gulong a_indent) { @@ -2528,12 +2724,15 @@ cr_statement_dump_media_rule (CRStatement * a_this, } /** - *Dumps an @import rule statement to a file. - *@param a_fp the destination file pointer. - *@param a_indent the number of white space indentations. + * cr_statement_dump_import_rule: + * + *@a_fp: the destination file pointer. + *@a_indent: the number of white space indentations. + * + *Dumps an \@import rule statement to a file. */ void -cr_statement_dump_import_rule (CRStatement * a_this, FILE * a_fp, +cr_statement_dump_import_rule (CRStatement const * a_this, FILE * a_fp, gulong a_indent) { gchar *str = NULL ; @@ -2551,6 +2750,10 @@ cr_statement_dump_import_rule (CRStatement * a_this, FILE * a_fp, } /** + * cr_statement_destroy: + * + * @a_this: the current instance of #CRStatement. + * *Destructor of #CRStatement. */ void diff --git a/src/libcroco/cr-statement.h b/src/libcroco/cr-statement.h index 5639ab730..74a233055 100644 --- a/src/libcroco/cr-statement.h +++ b/src/libcroco/cr-statement.h @@ -84,7 +84,7 @@ struct _CRStyleSheet ; typedef struct _CRStyleSheet CRStyleSheet; -/**The @import rule abstraction.*/ +/**The \@import rule abstraction.*/ typedef struct _CRAtImportRule CRAtImportRule ; struct _CRAtImportRule { @@ -102,7 +102,7 @@ struct _CRAtImportRule }; -/**abstraction of an @media rule*/ +/**abstraction of an \@media rule*/ struct _CRAtMediaRule { GList *media_list ; @@ -111,7 +111,7 @@ struct _CRAtMediaRule typedef struct _CRAtPageRule CRAtPageRule ; -/**The @page rule abstraction*/ +/**The \@page rule abstraction*/ struct _CRAtPageRule { /**a list of instances of #CRDeclaration*/ @@ -122,14 +122,14 @@ struct _CRAtPageRule CRString *pseudo ; } ; -/**The @charset rule abstraction*/ +/**The \@charset rule abstraction*/ typedef struct _CRAtCharsetRule CRAtCharsetRule ; struct _CRAtCharsetRule { CRString * charset ; }; -/**The abstaction of the @font-face rule.*/ +/**The abstaction of the \@font-face rule.*/ typedef struct _CRAtFontFaceRule CRAtFontFaceRule ; struct _CRAtFontFaceRule { @@ -176,8 +176,8 @@ enum CRStatementType *The abstraction of css statement as defined *in the chapter 4 and appendix D.1 of the css2 spec. *A statement is actually a double chained list of - *statements.A statement can be a ruleset, an @import - *rule, an @page rule etc ... + *statements.A statement can be a ruleset, an \@import + *rule, an \@page rule etc ... */ struct _CRStatement { @@ -314,7 +314,7 @@ cr_statement_ruleset_set_sel_list (CRStatement *a_this, CRSelector *a_sel_list) ; enum CRStatus -cr_statement_ruleset_get_sel_list (CRStatement *a_this, +cr_statement_ruleset_get_sel_list (CRStatement const *a_this, CRSelector **a_list) ; enum CRStatus @@ -346,11 +346,11 @@ cr_statement_at_import_rule_set_url (CRStatement *a_this, CRString *a_url) ; enum CRStatus -cr_statement_at_import_rule_get_url (CRStatement *a_this, +cr_statement_at_import_rule_get_url (CRStatement const *a_this, CRString **a_url) ; gint -cr_statement_at_media_nr_rules (CRStatement *a_this) ; +cr_statement_at_media_nr_rules (CRStatement const *a_this) ; CRStatement * cr_statement_at_media_get_from_list (CRStatement *a_this, int itemnr) ; @@ -360,7 +360,7 @@ cr_statement_at_page_rule_set_sel (CRStatement *a_this, CRSelector *a_sel) ; enum CRStatus -cr_statement_at_page_rule_get_sel (CRStatement *a_this, +cr_statement_at_page_rule_get_sel (CRStatement const *a_this, CRSelector **a_sel) ; enum CRStatus @@ -376,7 +376,7 @@ cr_statement_at_charset_rule_set_charset (CRStatement *a_this, CRString *a_charset) ; enum CRStatus -cr_statement_at_charset_rule_get_charset (CRStatement *a_this, +cr_statement_at_charset_rule_get_charset (CRStatement const *a_this, CRString **a_charset) ; enum CRStatus @@ -393,41 +393,41 @@ cr_statement_at_font_face_rule_add_decl (CRStatement *a_this, CRTerm *a_value) ; gchar * -cr_statement_to_string (CRStatement * a_this, gulong a_indent) ; +cr_statement_to_string (CRStatement const * a_this, gulong a_indent) ; gchar* -cr_statement_list_to_string (CRStatement *a_this, gulong a_indent) ; +cr_statement_list_to_string (CRStatement const *a_this, gulong a_indent) ; void -cr_statement_dump (CRStatement *a_this, FILE *a_fp, gulong a_indent) ; +cr_statement_dump (CRStatement const *a_this, FILE *a_fp, gulong a_indent) ; void -cr_statement_dump_ruleset (CRStatement * a_this, FILE * a_fp, +cr_statement_dump_ruleset (CRStatement const * a_this, FILE * a_fp, glong a_indent) ; void -cr_statement_dump_font_face_rule (CRStatement * a_this, +cr_statement_dump_font_face_rule (CRStatement const * a_this, FILE * a_fp, glong a_indent) ; void -cr_statement_dump_page (CRStatement * a_this, FILE * a_fp, +cr_statement_dump_page (CRStatement const * a_this, FILE * a_fp, gulong a_indent) ; void -cr_statement_dump_media_rule (CRStatement * a_this, +cr_statement_dump_media_rule (CRStatement const * a_this, FILE * a_fp, gulong a_indent) ; void -cr_statement_dump_import_rule (CRStatement * a_this, FILE * a_fp, +cr_statement_dump_import_rule (CRStatement const * a_this, FILE * a_fp, gulong a_indent) ; void -cr_statement_dump_charset (CRStatement * a_this, FILE * a_fp, +cr_statement_dump_charset (CRStatement const * a_this, FILE * a_fp, gulong a_indent) ; gint -cr_statement_nr_rules (CRStatement *a_this) ; +cr_statement_nr_rules (CRStatement const *a_this) ; CRStatement * cr_statement_get_from_list (CRStatement *a_this, int itemnr) ; diff --git a/src/libcroco/cr-string.c b/src/libcroco/cr-string.c index 7c656f54d..03a50f66e 100644 --- a/src/libcroco/cr-string.c +++ b/src/libcroco/cr-string.c @@ -68,7 +68,7 @@ cr_string_new_from_string (const gchar * a_string) *@return the newly instanciated #CRString. */ CRString * -cr_string_new_from_gstring (GString *a_string) +cr_string_new_from_gstring (GString const *a_string) { CRString *result = cr_string_new () ; if (!result) { @@ -85,7 +85,7 @@ cr_string_new_from_gstring (GString *a_string) } CRString * -cr_string_dup (CRString *a_this) +cr_string_dup (CRString const *a_this) { g_return_val_if_fail (a_this, NULL) ; @@ -100,7 +100,7 @@ cr_string_dup (CRString *a_this) } gchar * -cr_string_dup2 (CRString *a_this) +cr_string_dup2 (CRString const *a_this) { gchar *result = NULL ; @@ -121,7 +121,7 @@ cr_string_dup2 (CRString *a_this) *@param a_this the current instance of #CRString */ const gchar * -cr_string_peek_raw_str (CRString *a_this) +cr_string_peek_raw_str (CRString const *a_this) { g_return_val_if_fail (a_this, NULL) ; @@ -138,7 +138,7 @@ cr_string_peek_raw_str (CRString *a_this) *of -1 if no length can be returned. */ gint -cr_string_peek_raw_str_len (CRString *a_this) +cr_string_peek_raw_str_len (CRString const *a_this) { g_return_val_if_fail (a_this && a_this->stryng, -1) ; diff --git a/src/libcroco/cr-string.h b/src/libcroco/cr-string.h index 256453451..2700f0e2e 100644 --- a/src/libcroco/cr-string.h +++ b/src/libcroco/cr-string.h @@ -64,11 +64,11 @@ struct _CRString { CRString * cr_string_new (void) ; CRString *cr_string_new_from_string (const gchar * a_string) ; -CRString * cr_string_new_from_gstring (GString *a_string) ; -CRString *cr_string_dup (CRString *a_this) ; -gchar *cr_string_dup2 (CRString *a_this) ; -const gchar *cr_string_peek_raw_str (CRString *a_this) ; -gint cr_string_peek_raw_str_len (CRString *a_this) ; +CRString * cr_string_new_from_gstring (GString const *a_string) ; +CRString *cr_string_dup (CRString const *a_this) ; +gchar *cr_string_dup2 (CRString const *a_this) ; +const gchar *cr_string_peek_raw_str (CRString const *a_this) ; +gint cr_string_peek_raw_str_len (CRString const *a_this) ; void cr_string_destroy (CRString *a_this) ; G_END_DECLS diff --git a/src/libcroco/cr-style.h b/src/libcroco/cr-style.h index 9abdef6b2..18aeaad09 100644 --- a/src/libcroco/cr-style.h +++ b/src/libcroco/cr-style.h @@ -80,7 +80,7 @@ enum CRPositionType POSITION_RELATIVE, POSITION_ABSOLUTE, POSITION_FIXED, - POSITION_INHERIT, + POSITION_INHERIT } ; enum CRFloatType diff --git a/src/libcroco/cr-stylesheet.c b/src/libcroco/cr-stylesheet.c index 06b27fcab..1b26c64bf 100644 --- a/src/libcroco/cr-stylesheet.c +++ b/src/libcroco/cr-stylesheet.c @@ -1,4 +1,4 @@ -/* -*- Mode: C; indent-tabs-mode: ni; c-basic-offset: 8 -*- */ +/* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 8 -*- */ /* * This file is part of The Croco Library @@ -55,11 +55,11 @@ cr_stylesheet_new (CRStatement * a_stmts) *@return the serialized stylesheet. */ gchar * -cr_stylesheet_to_string (CRStyleSheet *a_this) +cr_stylesheet_to_string (CRStyleSheet const *a_this) { gchar *str = NULL; GString *stringue = NULL; - CRStatement *cur_stmt = NULL; + CRStatement const *cur_stmt = NULL; g_return_val_if_fail (a_this, NULL); @@ -93,7 +93,7 @@ cr_stylesheet_to_string (CRStyleSheet *a_this) *@param a_fp the destination file */ void -cr_stylesheet_dump (CRStyleSheet * a_this, FILE * a_fp) +cr_stylesheet_dump (CRStyleSheet const * a_this, FILE * a_fp) { gchar *str = NULL ; @@ -113,7 +113,7 @@ cr_stylesheet_dump (CRStyleSheet * a_this, FILE * a_fp) *@return number of rules in the stylesheet. */ gint -cr_stylesheet_nr_rules (CRStyleSheet * a_this) +cr_stylesheet_nr_rules (CRStyleSheet const * a_this) { g_return_val_if_fail (a_this, -1); diff --git a/src/libcroco/cr-stylesheet.h b/src/libcroco/cr-stylesheet.h index 3766a284a..f35c94e37 100644 --- a/src/libcroco/cr-stylesheet.h +++ b/src/libcroco/cr-stylesheet.h @@ -84,10 +84,10 @@ struct _CRStyleSheet CRStyleSheet * cr_stylesheet_new (CRStatement *a_stmts) ; -gchar * cr_stylesheet_to_string (CRStyleSheet *a_this) ; -void cr_stylesheet_dump (CRStyleSheet *a_this, FILE *a_fp) ; +gchar * cr_stylesheet_to_string (CRStyleSheet const *a_this) ; +void cr_stylesheet_dump (CRStyleSheet const *a_this, FILE *a_fp) ; -gint cr_stylesheet_nr_rules (CRStyleSheet *a_this) ; +gint cr_stylesheet_nr_rules (CRStyleSheet const *a_this) ; CRStatement * cr_stylesheet_statement_get_from_list (CRStyleSheet *a_this, int itemnr) ; diff --git a/src/libcroco/cr-term.c b/src/libcroco/cr-term.c index ccdff2522..09b6354db 100644 --- a/src/libcroco/cr-term.c +++ b/src/libcroco/cr-term.c @@ -275,10 +275,10 @@ cr_term_prepend_term (CRTerm * a_this, CRTerm * a_new_term) *form of #CRTerm. MUST BE FREED BY THE CALLER using g_free(). */ guchar * -cr_term_to_string (CRTerm * a_this) +cr_term_to_string (CRTerm const * a_this) { GString *str_buf = NULL; - CRTerm *cur = NULL; + CRTerm const *cur = NULL; guchar *result = NULL; gchar *content = NULL; @@ -472,7 +472,7 @@ cr_term_to_string (CRTerm * a_this) } guchar * -cr_term_one_to_string (CRTerm * a_this) +cr_term_one_to_string (CRTerm const * a_this) { GString *str_buf = NULL; guchar *result = NULL; @@ -675,7 +675,7 @@ cr_term_one_to_string (CRTerm * a_this) *@param a_fp the destination file pointer. */ void -cr_term_dump (CRTerm * a_this, FILE * a_fp) +cr_term_dump (CRTerm const * a_this, FILE * a_fp) { guchar *content = NULL; @@ -695,9 +695,9 @@ cr_term_dump (CRTerm * a_this, FILE * a_fp) *@return number of terms in the expression. */ int -cr_term_nr_values (CRTerm *a_this) +cr_term_nr_values (CRTerm const *a_this) { - CRTerm *cur = NULL ; + CRTerm const *cur = NULL ; int nr = 0; g_return_val_if_fail (a_this, -1) ; diff --git a/src/libcroco/cr-term.h b/src/libcroco/cr-term.h index ae8b234c5..e85867afb 100644 --- a/src/libcroco/cr-term.h +++ b/src/libcroco/cr-term.h @@ -169,13 +169,13 @@ CRTerm * cr_term_append_term (CRTerm *a_this, CRTerm *a_new_term) ; CRTerm * cr_term_prepend_term (CRTerm *a_this, CRTerm *a_new_term) ; -guchar * cr_term_to_string (CRTerm *a_this) ; +guchar * cr_term_to_string (CRTerm const *a_this) ; -guchar * cr_term_one_to_string (CRTerm * a_this) ; +guchar * cr_term_one_to_string (CRTerm const * a_this) ; -void cr_term_dump (CRTerm *a_this, FILE *a_fp) ; +void cr_term_dump (CRTerm const *a_this, FILE *a_fp) ; -int cr_term_nr_values (CRTerm *a_this) ; +int cr_term_nr_values (CRTerm const *a_this) ; CRTerm * cr_term_get_from_list (CRTerm *a_this, int itemnr) ; diff --git a/src/libcroco/cr-tknzr.c b/src/libcroco/cr-tknzr.c index 859b6c553..11ecd15e0 100644 --- a/src/libcroco/cr-tknzr.c +++ b/src/libcroco/cr-tknzr.c @@ -448,38 +448,49 @@ cr_tknzr_parse_comment (CRTknzr * a_this, READ_NEXT_CHAR (a_this, &cur_char); ENSURE_PARSING_COND (cur_char == '*'); comment = cr_string_new (); - for (;;) { + for (;;) { /* [^*]* */ + PEEK_NEXT_CHAR (a_this, &next_char); + if (next_char == '*') + break; READ_NEXT_CHAR (a_this, &cur_char); - - /*make sure there are no nested comments */ - if (cur_char == '/') { + g_string_append_unichar (comment->stryng, cur_char); + } + /* Stop condition: next_char == '*' */ + for (;;) { /* \*+ */ + READ_NEXT_CHAR(a_this, &cur_char); + ENSURE_PARSING_COND (cur_char == '*'); + g_string_append_unichar (comment->stryng, cur_char); + PEEK_NEXT_CHAR (a_this, &next_char); + if (next_char != '*') + break; + } + /* Stop condition: next_char != '*' */ + for (;;) { /* ([^/][^*]*\*+)* */ + if (next_char == '/') + break; + READ_NEXT_CHAR(a_this, &cur_char); + g_string_append_unichar (comment->stryng, cur_char); + for (;;) { /* [^*]* */ + PEEK_NEXT_CHAR (a_this, &next_char); + if (next_char == '*') + break; READ_NEXT_CHAR (a_this, &cur_char); - ENSURE_PARSING_COND (cur_char != '*'); - g_string_append_c (comment->stryng, '/'); - g_string_append_unichar (comment->stryng, - cur_char); - continue; + g_string_append_unichar (comment->stryng, cur_char); } - - /*Detect the end of the comments region */ - if (cur_char == '*') { + /* Stop condition: next_char = '*', no need to verify, because peek and read exit to error anyway */ + for (;;) { /* \*+ */ + READ_NEXT_CHAR(a_this, &cur_char); + ENSURE_PARSING_COND (cur_char == '*'); + g_string_append_unichar (comment->stryng, cur_char); PEEK_NEXT_CHAR (a_this, &next_char); - - if (next_char == '/') { - /* - *end of comments region - *Now, call the right SAC callback. - */ - SKIP_CHARS (a_this, 1) ; - status = CR_OK; + if (next_char != '*') break; - } else { - g_string_append_c (comment->stryng, - '*'); - } } - g_string_append_unichar (comment->stryng, cur_char); + /* Continue condition: next_char != '*' */ } + /* Stop condition: next_char == '\/' */ + READ_NEXT_CHAR(a_this, &cur_char); + g_string_append_unichar (comment->stryng, cur_char); if (status == CR_OK) { cr_parsing_location_copy (&comment->location, @@ -562,39 +573,16 @@ cr_tknzr_parse_unicode_escape (CRTknzr * a_this, cur_char_val = 10 + (cur_char - 'A'); } - unicode = unicode * 10 + cur_char_val; + unicode = unicode * 16 + cur_char_val; PEEK_NEXT_CHAR (a_this, &cur_char); } - if (occur == 5) { - /* - *the unicode escape is 6 digit length - */ - - /* - *parse one space that may - *appear just after the unicode - *escape. - */ - cr_tknzr_parse_w (a_this, &tmp_char_ptr1, - &tmp_char_ptr2, NULL); - status = CR_OK; - } else { - /* - *The unicode escape is less than - *6 digit length. The character - *that comes right after the escape - *must be a white space. - */ - status = cr_tknzr_parse_w (a_this, &tmp_char_ptr1, - &tmp_char_ptr2, NULL); - } - - if (status == CR_OK) { - *a_unicode = unicode; - return CR_OK; - } + /* Eat a whitespace if possible. */ + cr_tknzr_parse_w (a_this, &tmp_char_ptr1, + &tmp_char_ptr2, NULL); + *a_unicode = unicode; + return CR_OK; error: /* @@ -2106,18 +2094,8 @@ cr_tknzr_get_next_token (CRTknzr * a_this, CRToken ** a_tk) } goto done; } - } else { - status = cr_tknzr_parse_ident (a_this, &str); - if (status == CR_OK && str) { - status = cr_token_set_ident (token, str); - CHECK_PARSING_STATUS (status, TRUE); - if (str) { - cr_parsing_location_copy (&token->location, - &str->location) ; - } - goto done; - } - } + } + goto fallback; break; case 'r': @@ -2136,28 +2114,18 @@ cr_tknzr_get_next_token (CRTknzr * a_this, CRToken ** a_tk) goto done; } - } else { - status = cr_tknzr_parse_ident (a_this, &str); - if (status == CR_OK) { - status = cr_token_set_ident (token, str); - CHECK_PARSING_STATUS (status, TRUE); - if (str) { - cr_parsing_location_copy (&token->location, - &str->location) ; - } - str = NULL; - goto done; - } } + goto fallback; break; case '<': - if (BYTE (input, 2, NULL) == '-' - && BYTE (input, 3, NULL) == '-') { + if (BYTE (input, 2, NULL) == '!' + && BYTE (input, 3, NULL) == '-' + && BYTE (input, 4, NULL) == '-') { SKIP_CHARS (a_this, 1); cr_tknzr_get_parsing_location (a_this, &location) ; - SKIP_CHARS (a_this, 2); + SKIP_CHARS (a_this, 3); status = cr_token_set_cdo (token); CHECK_PARSING_STATUS (status, TRUE); cr_parsing_location_copy (&token->location, @@ -2538,6 +2506,7 @@ cr_tknzr_get_next_token (CRTknzr * a_this, CRToken ** a_tk) break; default: + fallback: /*process the fallback cases here */ if (next_char == '\\' diff --git a/src/libcroco/cr-token.c b/src/libcroco/cr-token.c index af95751d0..3dd73ac3e 100644 --- a/src/libcroco/cr-token.c +++ b/src/libcroco/cr-token.c @@ -46,6 +46,7 @@ cr_token_clear (CRToken * a_this) switch (a_this->type) { case S_TK: case CDO_TK: + case CDC_TK: case INCLUDES_TK: case DASHMATCH_TK: case PAGE_SYM_TK: diff --git a/src/libcroco/cr-utils.c b/src/libcroco/cr-utils.c index 487cf4b95..a51c76920 100644 --- a/src/libcroco/cr-utils.c +++ b/src/libcroco/cr-utils.c @@ -1299,10 +1299,10 @@ cr_utils_dump_n_chars2 (guchar a_char, GString * a_string, glong a_nb) *@param a_list_of_strings the list of strings to be duplicated. */ GList * -cr_utils_dup_glist_of_string (GList * a_list_of_strings) +cr_utils_dup_glist_of_string (GList const * a_list_of_strings) { - GList *cur = NULL, - *result = NULL; + GList const *cur = NULL; + GList *result = NULL; g_return_val_if_fail (a_list_of_strings, NULL); @@ -1325,16 +1325,17 @@ cr_utils_dup_glist_of_string (GList * a_list_of_strings) *happened. */ GList * -cr_utils_dup_glist_of_cr_string (GList * a_list_of_strings) +cr_utils_dup_glist_of_cr_string (GList const * a_list_of_strings) { - GList *cur = NULL, *result = NULL; + GList const *cur = NULL; + GList *result = NULL; g_return_val_if_fail (a_list_of_strings, NULL); for (cur = a_list_of_strings; cur; cur = cur->next) { CRString *str = NULL; - str = cr_string_dup ((CRString *) cur->data) ; + str = cr_string_dup ((CRString const *) cur->data) ; if (str) result = g_list_append (result, str); } diff --git a/src/libcroco/cr-utils.h b/src/libcroco/cr-utils.h index 060842aef..3959b1037 100644 --- a/src/libcroco/cr-utils.h +++ b/src/libcroco/cr-utils.h @@ -239,10 +239,10 @@ cr_utils_dump_n_chars2 (guchar a_char, GString *a_string, glong a_nb) ; GList * -cr_utils_dup_glist_of_string (GList *a_list) ; +cr_utils_dup_glist_of_string (GList const *a_list) ; GList * -cr_utils_dup_glist_of_cr_string (GList * a_list_of_strings) ; +cr_utils_dup_glist_of_cr_string (GList const * a_list_of_strings) ; G_END_DECLS |