2007-06-07 Emmanuele Bassi <ebassi@openedhand.com>

* clutter/*: Move documentation from the templates into the
	source code.

clutter/clutter-fixed.c

@@ -23,8 +23,42 @@
  * Boston, MA 02111-1307, USA.
  */
 
+#include "config.h"
+
 #include <clutter-fixed.h>
 
+/**
+ * SECTION:clutter-fixed
+ * @short_description: Fixed Point API
+ *
+ * Clutter has a fixed point API targeted at platforms without a floating
+ * point unit, such as embedded devices. This API should be preferred to
+ * the floating point one as it does not trigger the slow path of software
+ * emulation, relying on integer math for fixed-to-floating and
+ * floating-to-fixed conversion.
+ *
+ * Basic rules of Fixed Point arithmethic:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>Two fixed point numbers can be directly added and
+ *     subtracted.</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>To add other numerical type to a fixed point number it has to
+ *     be first converted to fixed point.</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>A fixed point number can be directly multiplied or divided by
+ *     an integer.</para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>Two fixed point numbers can only be multiplied and divided by the
+ *     provided #CLUTTER_FIXED_MUL and #CLUTTER_FIXED_DIV macros.</para>
+ *   </listitem>
+ * </itemizedlist>
+ */
+
 /* pre-computed sin table for 1st quadrant
  *
  * Currently contains 257 entries.