[doc] Split unstable api into section of its own.

13 files changed, 95 insertions, 94 deletions

diff --git a/ccss-doc/ccss-docs.sgml b/ccss-doc/ccss-docs.sgml
index ea526b8..37c213a 100644
--- a/ccss-doc/ccss-docs.sgml
+++ b/ccss-doc/ccss-docs.sgml
@@ -2,21 +2,24 @@
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 
-<!ENTITY ccss_background_t   SYSTEM "xml/background.xml">
-<!ENTITY ccss_block_t        SYSTEM "xml/block.xml">
-<!ENTITY ccss_border_t			 SYSTEM "xml/border.xml">
-<!ENTITY ccss_border_image_t SYSTEM "xml/border-image.xml">
-<!ENTITY ccss_color_t        SYSTEM "xml/color.xml">
-<!ENTITY ccss_function_t     SYSTEM "xml/function.xml">
-<!ENTITY ccss_grammar_t      SYSTEM "xml/grammar.xml">
-<!ENTITY ccss_node_t         SYSTEM "xml/node.xml">
-<!ENTITY ccss_padding_t      SYSTEM "xml/padding.xml">
-<!ENTITY ccss_position_t     SYSTEM "xml/position.xml">
-<!ENTITY ccss_property_t     SYSTEM "xml/property.xml">
-<!ENTITY ccss_style_t        SYSTEM "xml/style.xml">
-<!ENTITY ccss_stylesheet_t   SYSTEM "xml/stylesheet.xml">
+<!ENTITY ccss_background_t        SYSTEM "xml/background.xml">
+<!ENTITY ccss_block_t             SYSTEM "xml/block.xml">
+<!ENTITY ccss_border_t			      SYSTEM "xml/border.xml">
+<!ENTITY ccss_border_image_t      SYSTEM "xml/border-image.xml">
+<!ENTITY ccss_color_t             SYSTEM "xml/color.xml">
+<!ENTITY ccss_color_impl_t        SYSTEM "xml/color-impl.xml">
+<!ENTITY ccss_function_t          SYSTEM "xml/function.xml">
+<!ENTITY ccss_function_impl_t     SYSTEM "xml/function-impl.xml">
+<!ENTITY ccss_grammar_t           SYSTEM "xml/grammar.xml">
+<!ENTITY ccss_node_t              SYSTEM "xml/node.xml">
+<!ENTITY ccss_padding_t           SYSTEM "xml/padding.xml">
+<!ENTITY ccss_position_t          SYSTEM "xml/position.xml">
+<!ENTITY ccss_property_t          SYSTEM "xml/property.xml">
+<!ENTITY ccss_property_impl_t     SYSTEM "xml/property-impl.xml">
+<!ENTITY ccss_style_t             SYSTEM "xml/style.xml">
+<!ENTITY ccss_stylesheet_t        SYSTEM "xml/stylesheet.xml">
 
-<!ENTITY TreeIndex           SYSTEM "xml/tree_index.sgml">
+<!ENTITY TreeIndex                SYSTEM "xml/tree_index.sgml">
 
 ]>
 <book id="index">
@@ -102,6 +105,12 @@ TODO.
     &ccss_style_t;
     &ccss_stylesheet_t;
   </chapter>
+  <chapter id="unstable">
+    <title>Unstable interfaces</title>
+    &ccss_color_impl_t;
+    &ccss_function_impl_t;
+    &ccss_property_impl_t;
+  </chapter>
  </part>
 <index id="ccss-index">
 &TreeIndex;
diff --git a/ccss-doc/ccss-sections.txt b/ccss-doc/ccss-sections.txt
index b3bd7e9..e5b6207 100644
--- a/ccss-doc/ccss-sections.txt
+++ b/ccss-doc/ccss-sections.txt
@@ -68,6 +68,11 @@ ccss_color_get_alpha
 ccss_color_get_blue
 ccss_color_get_green
 ccss_color_get_red
+</SECTION>
+
+<SECTION>
+<TITLE>ccss_color_t internals</TITLE>
+<FILE>color-impl</FILE>
 ccss_color_parse
 </SECTION>
 
@@ -83,6 +88,13 @@ ccss_function_reference
 </SECTION>
 
 <SECTION>
+<TITLE>ccss_function_t internals</TITLE>
+<FILE>function-impl</FILE>
+ccss_grammar_add_functions
+ccss_grammar_invoke_function
+</SECTION>
+
+<SECTION>
 <TITLE>ccss_grammar_t</TITLE>
 <FILE>grammar</FILE>
 ccss_grammar_t
@@ -93,12 +105,10 @@ ccss_grammar_reference
 ccss_grammar_get_reference_count
 ccss_grammar_add_properties
 ccss_grammar_lookup_property
-ccss_grammar_add_functions
 ccss_grammar_lookup_function
 ccss_grammar_create_stylesheet
 ccss_grammar_create_stylesheet_from_buffer
 ccss_grammar_create_stylesheet_from_file
-ccss_grammar_invoke_function
 </SECTION>
 
 <TITLE>ccss_node_t</TITLE>
@@ -178,17 +188,23 @@ ccss_position_serialize
 <FILE>property</FILE>
 ccss_property_class_t
 ccss_property_t
-ccss_property_generic_t
 ccss_property_state_t
 ccss_property_type_t
+ccss_property_get_state
+ccss_property_state_serialize
+</SECTION>
+
+<SECTION>
+<TITLE>ccss_property_t internals</TITLE>
+<FILE>property-impl</FILE>
 ccss_property_create_f
 ccss_property_destroy_f
 ccss_property_convert_f
 ccss_property_factory_f
 ccss_property_inherit_f
 ccss_property_serialize_f
+ccss_property_generic_t
 ccss_property_init
-ccss_property_get_state
-ccss_property_state_serialize
+ccss_property_parse_state
 </SECTION>
 
diff --git a/ccss/Makefile.am b/ccss/Makefile.am
index 513fd2e..bc955d6 100644
--- a/ccss/Makefile.am
+++ b/ccss/Makefile.am
@@ -52,7 +52,6 @@ libccss_1_la_SOURCES = \
 	ccss-position.c \
 	ccss-position-parser.h \
 	ccss-property.c \
-	ccss-property-generic.h \
 	ccss-property-parser.c \
 	ccss-property-parser.h \
 	ccss-selector.c \
diff --git a/ccss/ccss-background-parser.c b/ccss/ccss-background-parser.c
index aca7a77..56c4adf 100644
--- a/ccss/ccss-background-parser.c
+++ b/ccss/ccss-background-parser.c
@@ -26,6 +26,7 @@
 #include "ccss-background.h"
 #include "ccss-block.h"
 #include "ccss-color-impl.h"
+#include "ccss-function-impl.h"
 #include "ccss-position-parser.h"
 #include "ccss-property-impl.h"
 #include "config.h"
diff --git a/ccss/ccss-border-image-parser.c b/ccss/ccss-border-image-parser.c
index 213bba8..c58913c 100644
--- a/ccss/ccss-border-image-parser.c
+++ b/ccss/ccss-border-image-parser.c
@@ -22,6 +22,7 @@
 #include <string.h>
 #include "ccss-border-image.h"
 #include "ccss-border-image-parser.h"
+#include "ccss-function-impl.h"
 #include "ccss-grammar.h"
 #include "ccss-position-parser.h"
 #include "ccss-property-impl.h"
diff --git a/ccss/ccss-color-impl.h b/ccss/ccss-color-impl.h
index b76874a..00ce41c 100644
--- a/ccss/ccss-color-impl.h
+++ b/ccss/ccss-color-impl.h
@@ -19,13 +19,17 @@
  * MA 02110-1301, USA.
  */
 
-/*
- * Declarations for the implementation of custom colors.
+/**
+ * SECTION:color-impl
+ * @short_description: internal functionality associated to ccss_color_t.
+ * @see_also: #ccss_color_t
+ * @stability: Unstable
+ * @include: ccss/ccss-color-impl.h
+ *
+ * Declarations for the implementation of custom colours.
  * This declarations are not to be considered part of the stable
  * ccss interface. Use with care.
- *
- * FIXME: split out to a section of its own in the docs.
- */
+ **/
 
 #ifndef CCSS_COLOR_IMPL_H
 #define CCSS_COLOR_IMPL_H
diff --git a/ccss/ccss-color-parser.c b/ccss/ccss-color-parser.c
index d200885..4828705 100644
--- a/ccss/ccss-color-parser.c
+++ b/ccss/ccss-color-parser.c
@@ -25,6 +25,7 @@
 #include <string.h>
 #include <glib.h>
 #include "ccss-color-impl.h"
+#include "ccss-function-impl.h"
 #include "ccss-property-impl.h"
 #include "config.h"
 
diff --git a/ccss/ccss-function-impl.h b/ccss/ccss-function-impl.h
index fc08864..f9f9d8d 100644
--- a/ccss/ccss-function-impl.h
+++ b/ccss/ccss-function-impl.h
@@ -19,17 +19,22 @@
  * MA 02110-1301, USA.
  */
 
-/*
+/**
+ * SECTION:function-impl
+ * @short_description: internal functionality associated to ccss_function_t.
+ * @see_also: #ccss_function_t
+ * @stability: Unstable
+ * @include: ccss/ccss-function-impl.h
+ *
  * Declarations for the implementation of custom functions.
  * This declarations are not to be considered part of the stable
  * ccss interface. Use with care.
- *
- * FIXME: split out to a section of its own in the docs.
- */
+ **/
 
 #ifndef CCSS_FUNCTION_IMPL_H
 #define CCSS_FUNCTION_IMPL_H
 
+#include <libcroco/libcroco.h>
 #include <ccss/ccss-function.h>
 #include <ccss/ccss-macros.h>
 
@@ -57,6 +62,12 @@ void
 ccss_grammar_add_functions	(struct ccss_grammar_		*self,
 				 ccss_function_t		*functions);
 
+char *
+ccss_grammar_invoke_function	(struct ccss_grammar_ const	 *self,
+				 char const			 *function_name,
+				 CRTerm const			 *values,
+				 void				 *user_data);
+
 CCSS_END_DECLS
 
 #endif /* CCSS_FUNCTION_IMPL_H */
diff --git a/ccss/ccss-grammar-priv.h b/ccss/ccss-grammar-priv.h
index 05ef177..506b998 100644
--- a/ccss/ccss-grammar-priv.h
+++ b/ccss/ccss-grammar-priv.h
@@ -22,9 +22,6 @@
 #ifndef CCSS_GRAMMAR_PRIV_H
 #define CCSS_GRAMMAR_PRIV_H
 
-#include <stdbool.h>
-#include <stddef.h>
-#include <stdlib.h>
 #include <glib.h>
 #include <libcroco/libcroco.h>
 #include <ccss/ccss-grammar.h>
diff --git a/ccss/ccss-property-generic.h b/ccss/ccss-property-generic.h
deleted file mode 100644
index 2e0765b..0000000
--- a/ccss/ccss-property-generic.h
+++ /dev/null
@@ -1,50 +0,0 @@
-/* vim: set ts=8 sw=8 noexpandtab: */
-
-/* The `C' CSS Library.
- * Copyright (C) 2008 Robert Staudinger
- * Copyright (C) 2009 Intel Corporation
- *
- * This  library is free  software; you can  redistribute it and/or
- * modify it  under  the terms  of the  GNU Lesser  General  Public
- * License  as published  by the Free  Software  Foundation; either
- * version 2 of the License, or (at your option) any later version.
- *
- * This library is distributed  in the hope that it will be useful,
- * but  WITHOUT ANY WARRANTY; without even  the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public
- * License  along  with  this library;  if not,  write to  the Free
- * Software Foundation, Inc., 51  Franklin St, Fifth Floor, Boston,
- * MA 02110-1301, USA.
- */
-
-#ifndef CCSS_PROPERTY_GENERIC_H
-#define CCSS_PROPERTY_GENERIC_H
-
-#include <libcroco/libcroco.h>
-#include <ccss/ccss-macros.h>
-#include <ccss/ccss-property.h>
-
-CCSS_BEGIN_DECLS
-
-/**
- * ccss_property_generic_t:
- * @base:	base property.
- * @name:	name of the property, e.g. %color.
- * @values:	linked list of values.
- *
- * Implementation of a generic, single-value property.
- **/
-typedef struct {
-	ccss_property_t		 base;
-
-	char			*name;
-	CRTerm			*values;
-} ccss_property_generic_t;
-
-CCSS_END_DECLS
-
-#endif /* CCSS_PROPERTY_GENERIC_H */
-
diff --git a/ccss/ccss-property-impl.h b/ccss/ccss-property-impl.h
index 39f9716..39da513 100644
--- a/ccss/ccss-property-impl.h
+++ b/ccss/ccss-property-impl.h
@@ -19,13 +19,17 @@
  * MA 02110-1301, USA.
  */
 
-/*
+/**
+ * SECTION:property-impl
+ * @short_description: internal functionality associated to ccss_property_t.
+ * @see_also: #ccss_property_t
+ * @stability: Unstable
+ * @include: ccss/ccss-property-impl.h
+ *
  * Declarations for the implementation of custom properties.
  * This declarations are not to be considered part of the stable
  * ccss interface. Use with care.
- *
- * FIXME: split out to a section of its own in the docs.
- */
+ **/
 
 #ifndef CCSS_PROPERTY_IMPL_H
 #define CCSS_PROPERTY_IMPL_H
@@ -148,6 +152,22 @@ struct ccss_property_class_ {
 	void (*_padding_4) (void);
 };
 
+/**
+ * ccss_property_generic_t:
+ * @base:	base property.
+ * @name:	name of the property, e.g. %color.
+ * @values:	linked list of values.
+ *
+ * Implementation of a generic, single-value property.
+ **/
+typedef struct {
+	/*< private >*/
+	CCSS_DEPRECATED (ccss_property_t	 base);
+
+	CCSS_DEPRECATED (char			*name);
+	CCSS_DEPRECATED (CRTerm			*values);
+} ccss_property_generic_t;
+
 ccss_property_state_t
 ccss_property_parse_state       (CRTerm const			**value);
 
@@ -165,12 +185,6 @@ ccss_style_interpret_property   (struct ccss_style_ const	 *self,
 				 void				 *user_data,
 				 ccss_property_t		**property);
 
-char *
-ccss_grammar_invoke_function	(struct ccss_grammar_ const	 *self,
-				 char const			 *function_name,
-				 CRTerm const			 *values,
-				 void				 *user_data);
-
 CCSS_END_DECLS
 
 #endif /* CCSS_PROPERTY_IMPL_H */
diff --git a/ccss/ccss-property-parser.c b/ccss/ccss-property-parser.c
index ffd190e..10fffa3 100644
--- a/ccss/ccss-property-parser.c
+++ b/ccss/ccss-property-parser.c
@@ -24,7 +24,6 @@
 #include <libcroco/libcroco.h>
 #include "ccss-block.h"
 #include "ccss-grammar.h"
-#include "ccss-property-generic.h"
 #include "ccss-property-impl.h"
 #include "ccss-property-parser.h"
 #include "config.h"
diff --git a/ccss/ccss-style.c b/ccss/ccss-style.c
index cadd3df..05454b8 100644
--- a/ccss/ccss-style.c
+++ b/ccss/ccss-style.c
@@ -22,7 +22,6 @@
 
 #include <string.h>
 #include <glib.h>
-#include "ccss-property-generic.h"
 #include "ccss-property-impl.h"
 #include "ccss-style-priv.h"
 #include "config.h"