Merge upstream libcroco 0.6.3 changes

(bzr r12765)

1 files changed, 428 insertions, 225 deletions

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