Merge branch 'master-next' into 'master'

Release Cairo 1.18.0

See merge request cairo/cairo!517

20 files changed, 453 insertions, 101 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index aefe7d56a..9384e0abd 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -115,11 +115,6 @@ fedora image:
     # gets run separately
     - meson test -C builddir --no-suite=slow --print-errorlogs
 
-    # TODO: These aren't set up as Meson tests yet
-    - (cd doc/public && bash "check-doc-syntax.sh")
-    # FIXME: The following line really needs gtk-doc to run first
-    - (cd doc/public && DOC_MODULE=cairo bash "check-doc-coverage.sh")
-
     - meson install -C builddir
   artifacts:
     expire_in: "7 days"
diff --git a/NEWS b/NEWS
index a1fcf0d9f..49acef870 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,47 @@
+Release 1.18.0 (2023-09-20 Emmanuele Bassi <ebassi@gnome.org>)
+==============================================================
+
+The first stable cairo release in five years should be cause for celebration.
+
+All the API added in the 1.17 development cycle is now considered stable, and
+will not change.
+
+Many thanks to all the contributors for this release.
+
+The cairo-sphinx tool has been removed; we could not find any instruction on
+how to use it, and no user answered our call for help. If you were using
+cairo-sphinx, please reach out to the cairo maintainers.
+
+Cairo now implements Type 3 color fonts for PDF. Thanks to Adrian Johnson for
+his work on this feature.
+
+Khaled Hosny contributed multiple documentation fixes, to ensure that the
+cairo API reference is up to date. Khaled also fixed multiple compiler
+warnings generated when building cairo.
+
+The XML surface has been removed; it was disabled by default when building
+cairo, and we could not find any downstream distributor that would enable
+it.
+
+The Tee surface is now automatically enabled. Downstream distributors of
+cairo have been enabling for years it in order to build Firefox.
+
+Fujii Hironori and Adrian Johnson fixed multiple issues with the DWrite
+font backend.
+
+John Ralls improved the Quartz surface; mainly, Quartz surfaces now use
+the main display ColorSpace, speeding up rendering operations.
+
+Cairo now hides all private symbols by default on every platform; the old
+"slim" symbols hack to alias internally used symbols has been dropped, in
+favor of using `-Bsymbolic-functions` with toolchains that support it.
+
+Uli Schlachter fixed multiple memory leaks in the code base and test suite,
+and helped with many reviews and general maintenance.
+
+Marc Jeanmougin added new API to expose the Pixman dithering filter to cairo
+patterns; this is currently implemented only for image surfaces.
+
 Release 1.17.8 (2023-01-30 Emmanuele Bassi <ebassi@gnome.org>)
 ==============================================================
 
diff --git a/doc/public/cairo-docs.xml b/doc/public/cairo-docs.xml
index cc7c9aa04..6bfbddf64 100644
--- a/doc/public/cairo-docs.xml
+++ b/doc/public/cairo-docs.xml
@@ -48,6 +48,7 @@
     <xi:include href="xml/cairo-xlib-xrender.xml"/>
     <xi:include href="xml/cairo-script.xml"/>
     <xi:include href="xml/cairo-surface-observer.xml"/>
+    <xi:include href="xml/cairo-tee.xml"/>
   </chapter>
   <chapter id="cairo-support">
     <title>Utilities</title>
@@ -56,53 +57,53 @@
     <xi:include href="xml/cairo-version.xml"/>
     <xi:include href="xml/cairo-types.xml"/>
   </chapter>
-  <index id="api-index-all">
+  <chapter id="api-index-all">
     <title>Index</title>
     <xi:include href="xml/api-index-full.xml"/>
-  </index>
+  </chapter>
   <!--index id="deprecated-api-index">
     <title>Index of deprecated symbols</title>
     <xi:include href="xml/api-index-deprecated.xml"/>
   </index-->
-  <index id="api-index-1-0">
+  <chapter id="api-index-1-0">
     <title>Index of new symbols in 1.0</title>
     <xi:include href="xml/api-index-1.0.xml"/>
-  </index>
-  <index id="api-index-1-2">
+  </chapter>
+  <chapter id="api-index-1-2">
     <title>Index of new symbols in 1.2</title>
     <xi:include href="xml/api-index-1.2.xml"/>
-  </index>
-  <index id="api-index-1-4">
+  </chapter>
+  <chapter id="api-index-1-4">
     <title>Index of new symbols in 1.4</title>
     <xi:include href="xml/api-index-1.4.xml"/>
-  </index>
-  <index id="api-index-1-6">
+  </chapter>
+  <chapter id="api-index-1-6">
     <title>Index of new symbols in 1.6</title>
     <xi:include href="xml/api-index-1.6.xml"/>
-  </index>
-  <index id="api-index-1-8">
+  </chapter>
+  <chapter id="api-index-1-8">
     <title>Index of new symbols in 1.8</title>
     <xi:include href="xml/api-index-1.8.xml"/>
-  </index>
-  <index id="api-index-1-10">
+  </chapter>
+  <chapter id="api-index-1-10">
     <title>Index of new symbols in 1.10</title>
     <xi:include href="xml/api-index-1.10.xml"/>
-  </index>
-  <index id="api-index-1-12">
+  </chapter>
+  <chapter id="api-index-1-12">
     <title>Index of new symbols in 1.12</title>
     <xi:include href="xml/api-index-1.12.xml"/>
-  </index>
-  <index id="api-index-1-14">
+  </chapter>
+  <chapter id="api-index-1-14">
     <title>Index of new symbols in 1.14</title>
     <xi:include href="xml/api-index-1.14.xml"/>
-  </index>
-  <index id="api-index-1-16">
+  </chapter>
+  <chapter id="api-index-1-16">
     <title>Index of new symbols in 1.16</title>
     <xi:include href="xml/api-index-1.16.xml"/>
-  </index>
-  <index id="api-index-1-18">
+  </chapter>
+  <chapter id="api-index-1-18">
     <title>Index of new symbols in 1.18</title>
     <xi:include href="xml/api-index-1.18.xml"/>
-  </index>
-  <xi:include href="language-bindings.xml"/>
+  </chapter>
+  <xi:include href="xml/language-bindings.xml"/>
 </book>
diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
index f6dc84813..52bbbb231 100644
--- a/doc/public/cairo-sections.txt
+++ b/doc/public/cairo-sections.txt
@@ -410,8 +410,8 @@ cairo_pattern_get_reference_count
 cairo_pattern_set_user_data
 cairo_pattern_get_user_data
 cairo_dither_t
-cairo_set_dither
-cairo_get_dither
+cairo_pattern_set_dither
+cairo_pattern_get_dither
 </SECTION>
 
 <SECTION>
diff --git a/src/cairo-array.c b/src/cairo-array.c
index 064b63f29..a4a4f8c84 100644
--- a/src/cairo-array.c
+++ b/src/cairo-array.c
@@ -40,7 +40,7 @@
 #include "cairo-array-private.h"
 #include "cairo-error-private.h"
 
-/**
+/*< private >
  * _cairo_array_init:
  *
  * Initialize a new #cairo_array_t object to store objects each of size
@@ -63,7 +63,7 @@ _cairo_array_init (cairo_array_t *array, unsigned int element_size)
     array->elements = NULL;
 }
 
-/**
+/*< private >
  * _cairo_array_fini:
  * @array: A #cairo_array_t
  *
@@ -77,7 +77,7 @@ _cairo_array_fini (cairo_array_t *array)
     free (array->elements);
 }
 
-/**
+/*< private >
  * _cairo_array_grow_by:
  * @array: a #cairo_array_t
  *
@@ -125,7 +125,7 @@ _cairo_array_grow_by (cairo_array_t *array, unsigned int additional)
     return CAIRO_STATUS_SUCCESS;
 }
 
-/**
+/*< private >
  * _cairo_array_truncate:
  * @array: a #cairo_array_t
  *
@@ -140,7 +140,7 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
 	array->num_elements = num_elements;
 }
 
-/**
+/*< private >
  * _cairo_array_index:
  * @array: a #cairo_array_t
  *
@@ -149,7 +149,7 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
  * pointer may be used for further direct indexing with []. For
  * example:
  *
- * <informalexample><programlisting>
+ * |[<!-- language="C" -->
  *	cairo_array_t array;
  *	double *values;
  *
@@ -159,7 +159,7 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
  *	values = _cairo_array_index (&array, 0);
  *      for (i = 0; i < _cairo_array_num_elements (&array); i++)
  *	    ... use values[i] here ...
- * </programlisting></informalexample>
+ * ]|
  *
  * Returns: A pointer to the object stored at @index.
  **/
@@ -185,7 +185,7 @@ _cairo_array_index (cairo_array_t *array, unsigned int index)
     return array->elements + (size_t)index * array->element_size;
 }
 
-/**
+/*< private >
  * _cairo_array_index_const:
  * @array: a #cairo_array_t
  *
@@ -194,7 +194,7 @@ _cairo_array_index (cairo_array_t *array, unsigned int index)
  * pointer may be used for further direct indexing with []. For
  * example:
  *
- * <informalexample><programlisting>
+ * |[<!-- language="C" --.
  *	cairo_array_t array;
  *	const double *values;
  *
@@ -204,7 +204,7 @@ _cairo_array_index (cairo_array_t *array, unsigned int index)
  *	values = _cairo_array_index_const (&array, 0);
  *      for (i = 0; i < _cairo_array_num_elements (&array); i++)
  *	    ... read values[i] here ...
- * </programlisting></informalexample>
+ * ]|
  *
  * Returns: A pointer to the object stored at @index.
  **/
@@ -230,7 +230,7 @@ _cairo_array_index_const (const cairo_array_t *array, unsigned int index)
     return array->elements + (size_t)index * array->element_size;
 }
 
-/**
+/*< private >
  * _cairo_array_copy_element:
  * @array: a #cairo_array_t
  *
@@ -245,7 +245,7 @@ _cairo_array_copy_element (const cairo_array_t *array,
     memcpy (dst, _cairo_array_index_const (array, index), array->element_size);
 }
 
-/**
+/*< private >
  * _cairo_array_append:
  * @array: a #cairo_array_t
  *
@@ -267,7 +267,7 @@ _cairo_array_append (cairo_array_t	*array,
     return _cairo_array_append_multiple (array, element, 1);
 }
 
-/**
+/*< private >
  * _cairo_array_append_multiple:
  * @array: a #cairo_array_t
  *
@@ -296,7 +296,7 @@ _cairo_array_append_multiple (cairo_array_t	*array,
     return CAIRO_STATUS_SUCCESS;
 }
 
-/**
+/*< private >
  * _cairo_array_allocate:
  * @array: a #cairo_array_t
  *
@@ -329,7 +329,7 @@ _cairo_array_allocate (cairo_array_t	 *array,
     return CAIRO_STATUS_SUCCESS;
 }
 
-/**
+/*< private >
  * _cairo_array_num_elements:
  * @array: a #cairo_array_t
  *
@@ -343,7 +343,7 @@ _cairo_array_num_elements (const cairo_array_t *array)
     return array->num_elements;
 }
 
-/**
+/*< private >
  * _cairo_array_size:
  * @array: a #cairo_array_t
  *
@@ -358,7 +358,7 @@ _cairo_array_size (const cairo_array_t *array)
     return array->size;
 }
 
-/**
+/*< private >
  * _cairo_user_data_array_init:
  * @array: a #cairo_user_data_array_t
  *
@@ -373,7 +373,7 @@ _cairo_user_data_array_init (cairo_user_data_array_t *array)
     _cairo_array_init (array, sizeof (cairo_user_data_slot_t));
 }
 
-/**
+/*< private >
  * _cairo_user_data_array_fini:
  * @array: a #cairo_user_data_array_t
  *
@@ -400,7 +400,7 @@ _cairo_user_data_array_fini (cairo_user_data_array_t *array)
     _cairo_array_fini (array);
 }
 
-/**
+/*< private >
  * _cairo_user_data_array_get_data:
  * @array: a #cairo_user_data_array_t
  * @key: the address of the #cairo_user_data_key_t the user data was
@@ -433,7 +433,7 @@ _cairo_user_data_array_get_data (cairo_user_data_array_t     *array,
     return NULL;
 }
 
-/**
+/*< private >
  * _cairo_user_data_array_set_data:
  * @array: a #cairo_user_data_array_t
  * @key: the address of a #cairo_user_data_key_t to attach the user data to
@@ -543,7 +543,7 @@ _cairo_array_sort (const cairo_array_t *array, int (*compar)(const void *, const
     qsort (array->elements, array->num_elements, array->element_size, compar);
 }
 
-/**
+/*< private >
  * _cairo_array_pop_element:
  * @array: a #cairo_array_t
  * Returns: A TRUE if element successfully popped, FALSE if the array is empty.
@@ -563,7 +563,7 @@ _cairo_array_pop_element (cairo_array_t *array, void *dst)
     return FALSE;
 }
 
-/**
+/*< private >
  * _cairo_array_top_element:
  * @array: a #cairo_array_t
  * Returns: A pointer to the last of object or NULL if array is empty.
diff --git a/src/cairo-error.c b/src/cairo-error.c
index 1b9bd76be..2dd015f46 100644
--- a/src/cairo-error.c
+++ b/src/cairo-error.c
@@ -44,7 +44,7 @@
 
 #include <assert.h>
 
-/**
+/*< private >
  * _cairo_error:
  * @status: a status value indicating an error, (eg. not
  * %CAIRO_STATUS_SUCCESS)
diff --git a/src/cairo-list-inline.h b/src/cairo-list-inline.h
index 7d68917f0..959c03806 100644
--- a/src/cairo-list-inline.h
+++ b/src/cairo-list-inline.h
@@ -39,7 +39,7 @@
 
 #include "cairo-list-private.h"
 
-/**
+/*< private >
  * cairo_list_entry:
  * @ptr: the pointer to the #cairo_list_t member.
  * @type: the type of the struct.
@@ -56,7 +56,7 @@
 #define cairo_list_last_entry(ptr, type, member) \
 	cairo_list_entry((ptr)->prev, type, member)
 
-/**
+/*< private >
  * cairo_list_foreach:
  * @pos: a #cairo_list_t* to use as a loop variable.
  * @head: the list.
@@ -66,7 +66,7 @@
 #define cairo_list_foreach(pos, head)                                   \
 	for (pos = (head)->next; pos != (head);	pos = pos->next)
 
-/**
+/*< private >
  * cairo_list_foreach_entry:
  * @pos: a variable of type T * to use as a loop variable.
  * @type: the type of the entry struct
@@ -80,7 +80,7 @@
 	     &pos->member != (head);					\
 	     pos = cairo_list_entry(pos->member.next, type, member))
 
-/**
+/*< private >
  * cairo_list_foreach_entry_safe:
  * @pos: a variable of type T * to use as a loop variable.
  * @n: a variable of type T * that point to the next item after @pos.
@@ -92,7 +92,7 @@
  * iterating. @n is a temporary variable required to support safe
  * iterating.
  *
- * <informalexample><programlisting>
+ * |[<!-- language="C" -->
  *      struct foo {
  *          int a;
  *          cairo_list_t list;
@@ -107,7 +107,7 @@
  *          printf("%d\n", pos->a);
  *          cairo_list_del (pos);
  *      }
- * </programlisting></informalexample>
+ * ]|
  **/
 #define cairo_list_foreach_entry_safe(pos, n, type, head, member)	\
 	for (pos = cairo_list_entry ((head)->next, type, member),\
@@ -115,7 +115,7 @@
 	     &pos->member != (head);					\
 	     pos = n, n = cairo_list_entry (n->member.next, type, member))
 
-/**
+/*< private >
  * cairo_list_foreach_entry:
  * @pos: a variable of type T * to use as a loop variable.
  * @type: the type of the entry struct
@@ -129,7 +129,7 @@
 	     &pos->member != (head);					\
 	     pos = cairo_list_entry(pos->member.prev, type, member))
 
-/**
+/*< private >
  * cairo_list_foreach_entry_safe:
  * @pos: a variable of type T * to use as a loop variable.
  * @n: a variable of type T * that point to the next item after @pos.
@@ -175,7 +175,7 @@ cairo_list_validate_is_empty (const cairo_list_t *head)
 #define cairo_list_validate_is_empty(head)
 #endif
 
-/**
+/*< private >
  * cairo_list_init:
  * @entry: list entry to initialize
  *
@@ -200,7 +200,7 @@ __cairo_list_add (cairo_list_t *entry,
     prev->next = entry;
 }
 
-/**
+/*< private >
  * cairo_list_add:
  * @entry: new entry
  * @head: linked list head
@@ -216,7 +216,7 @@ cairo_list_add (cairo_list_t *entry, cairo_list_t *head)
     cairo_list_validate (head);
 }
 
-/**
+/*< private >
  * cairo_list_add_tail:
  * @entry: new entry
  * @head: linked list head
@@ -245,7 +245,7 @@ _cairo_list_del (cairo_list_t *entry)
     __cairo_list_del (entry->prev, entry->next);
 }
 
-/**
+/*< private >
  * cairo_list_del:
  * @entry: entry to remove
  *
@@ -258,7 +258,7 @@ cairo_list_del (cairo_list_t *entry)
     cairo_list_init (entry);
 }
 
-/**
+/*< private >
  * cairo_list_move:
  * @entry: entry to move
  * @head: linked list to move @entry to
@@ -274,7 +274,7 @@ cairo_list_move (cairo_list_t *entry, cairo_list_t *head)
     cairo_list_validate (head);
 }
 
-/**
+/*< private >
  * cairo_list_move_tail:
  * @entry: entry tp move
  * @head: linked list to move @entry to
@@ -290,7 +290,7 @@ cairo_list_move_tail (cairo_list_t *entry, cairo_list_t *head)
     cairo_list_validate (head);
 }
 
-/**
+/*< private >
  * cairo_list_move_list:
  * @old: List to move
  * @new: List to move to. Should be empty,
@@ -304,7 +304,7 @@ cairo_list_move_list (cairo_list_t *old, cairo_list_t *new)
     cairo_list_init (old);
 }
 
-/**
+/*< private >
  * cairo_list_is_first:
  * @entry: entry to check
  * @head: linked list
@@ -319,7 +319,7 @@ cairo_list_is_first (const cairo_list_t *entry,
     return entry->prev == head;
 }
 
-/**
+/*< private >
  * cairo_list_is_last:
  * @entry: entry to check
  * @head: linked list
@@ -334,7 +334,7 @@ cairo_list_is_last (const cairo_list_t *entry,
     return entry->next == head;
 }
 
-/**
+/*< private >
  * cairo_list_is_empty:
  * @head: linked list
  *
@@ -347,7 +347,7 @@ cairo_list_is_empty (const cairo_list_t *head)
     return head->next == head;
 }
 
-/**
+/*< private >
  * cairo_list_is_singular:
  * @head: linked list
  *
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index 23c43855c..fcaaf46b8 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -63,6 +63,14 @@
  * functions.
  **/
 
+/**
+ * CAIRO_HAS_MIME_SURFACE:
+ *
+ * Unused symbol, always defined.
+ *
+ * Since: 1.12
+ **/
+
 static freed_pool_t freed_pattern_pool[5];
 
 static const cairo_solid_pattern_t _cairo_pattern_nil = {
diff --git a/src/cairo-quartz-font.c b/src/cairo-quartz-font.c
index 1e7531356..0c868e026 100644
--- a/src/cairo-quartz-font.c
+++ b/src/cairo-quartz-font.c
@@ -51,6 +51,7 @@
  * @Short_Description: Font support via Core Text on Apple operating systems.
  * @See_Also: #cairo_font_face_t
  *
+ * Provide support for font faces via Core Text.
  **/
 
 /**
diff --git a/src/cairo-quartz-image-surface.c b/src/cairo-quartz-image-surface.c
index d09f5b5bc..9056a7b68 100644
--- a/src/cairo-quartz-image-surface.c
+++ b/src/cairo-quartz-image-surface.c
@@ -49,6 +49,15 @@
 #define SURFACE_ERROR_INVALID_SIZE (_cairo_surface_create_in_error(_cairo_error(CAIRO_STATUS_INVALID_SIZE)))
 #define SURFACE_ERROR_INVALID_FORMAT (_cairo_surface_create_in_error(_cairo_error(CAIRO_STATUS_INVALID_FORMAT)))
 
+/**
+ * CAIRO_HAS_QUARTZ_IMAGE_SURFACE:
+ *
+ * Defined if the Quartz image surface backend is available.
+ * This macro can be used to conditionally compile backend-specific code.
+ *
+ * Since: 1.10
+ **/
+
 static cairo_surface_t *
 _cairo_quartz_image_surface_create_similar (void *asurface,
 					    cairo_content_t content,
@@ -326,7 +335,7 @@ cairo_quartz_image_surface_create (cairo_surface_t *surface)
  * or %NULL if the quartz surface is not an image surface.
  *
  * Since: 1.6
- */
+ **/
 cairo_surface_t *
 cairo_quartz_image_surface_get_image (cairo_surface_t *surface)
 {
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index 3a0988899..70d1eab2a 100755
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -2661,7 +2661,7 @@ _cairo_scaled_glyph_set_path (cairo_scaled_glyph_t *scaled_glyph,
  * glyph, or NULL if foreground color not required.
  *
  * Sets the surface that was used to record the glyph.
- */
+ **/
 void
 _cairo_scaled_glyph_set_recording_surface (cairo_scaled_glyph_t *scaled_glyph,
 					   cairo_scaled_font_t  *scaled_font,
@@ -2694,7 +2694,7 @@ _cairo_scaled_glyph_set_recording_surface (cairo_scaled_glyph_t *scaled_glyph,
  * used when rendering the surface color.
  *
  * Sets the color surface of the glyph.
- */
+ **/
 void
 _cairo_scaled_glyph_set_color_surface (cairo_scaled_glyph_t  *scaled_glyph,
 	                               cairo_scaled_font_t   *scaled_font,
diff --git a/src/cairo-surface-observer.c b/src/cairo-surface-observer.c
index bf29d4219..83aa41801 100644
--- a/src/cairo-surface-observer.c
+++ b/src/cairo-surface-observer.c
@@ -60,8 +60,17 @@
  * @Short_Description: Observing other surfaces
  * @See_Also: #cairo_surface_t
  *
- * A surface that exists solely to watch another is doing.
- */
+ * A surface that exists solely to watch what another surface is doing.
+ **/
+
+/**
+ * CAIRO_HAS_OBSERVER_SURFACE:
+ *
+ * Defined if the observer surface backend is available.
+ * This macro can be used to conditionally compile backend-specific code.
+ *
+ * Since: 1.12
+ **/
 
 static const cairo_surface_backend_t _cairo_surface_observer_backend;
 
@@ -1382,8 +1391,8 @@ static const cairo_surface_backend_t _cairo_surface_observer_backend = {
  * the process it will log operations and times, which are fast, which are
  * slow, which are frequent, etc.
  *
- * The @mode parameter can be set to either CAIRO_SURFACE_OBSERVER_NORMAL
- * or CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS, to control whether or not
+ * The @mode parameter can be set to either %CAIRO_SURFACE_OBSERVER_NORMAL
+ * or %CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS, to control whether or not
  * the internal observer should record operations.
  *
  * Return value: a pointer to the newly allocated surface. The caller
@@ -1438,6 +1447,18 @@ _cairo_surface_observer_add_callback (cairo_list_t *head,
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_surface_observer_add_paint_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for paint operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for paint operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ **/
 cairo_status_t
 cairo_surface_observer_add_paint_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1456,6 +1477,18 @@ cairo_surface_observer_add_paint_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_mask_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for mask operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for mask operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ **/
 cairo_status_t
 cairo_surface_observer_add_mask_callback (cairo_surface_t *abstract_surface,
 					  cairo_surface_observer_callback_t func,
@@ -1474,6 +1507,18 @@ cairo_surface_observer_add_mask_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_fill_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for fill operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for fill operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ **/
 cairo_status_t
 cairo_surface_observer_add_fill_callback (cairo_surface_t *abstract_surface,
 					  cairo_surface_observer_callback_t func,
@@ -1492,6 +1537,18 @@ cairo_surface_observer_add_fill_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_stroke_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for stroke operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for stroke operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.12
+ **/
 cairo_status_t
 cairo_surface_observer_add_stroke_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1510,6 +1567,18 @@ cairo_surface_observer_add_stroke_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_glyphs_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for glyph operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for glyph operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_surface_observer_add_glyphs_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1528,6 +1597,18 @@ cairo_surface_observer_add_glyphs_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_flush_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback for flush operations
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for flush operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_surface_observer_add_flush_callback (cairo_surface_t *abstract_surface,
 					   cairo_surface_observer_callback_t func,
@@ -1546,6 +1627,18 @@ cairo_surface_observer_add_flush_callback (cairo_surface_t *abstract_surface,
 						 func, data);
 }
 
+/**
+ * cairo_surface_observer_add_finish_callback:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @func: callback function for the finish operation
+ * @data: closure to pass to the callback
+ *
+ * Adds a callback for finish operations on the observed surface.
+ *
+ * Returns: the status of the surface
+ *
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_surface_observer_add_finish_callback (cairo_surface_t *abstract_surface,
 					    cairo_surface_observer_callback_t func,
@@ -1966,6 +2059,18 @@ _cairo_observation_print (cairo_output_stream_t *stream,
     cairo_device_destroy (script);
 }
 
+/**
+ * cairo_surface_observer_print:
+ * @abstract_surface: a #cairo_surface_observer_t
+ * @write_func: callback for writing on a stream
+ * @closure: data to pass to @write_func
+ *
+ * Prints the observer log using the given callback.
+ *
+ * Returns: the status of the print operation
+ *
+ * Since: 1.12
+ **/
 cairo_status_t
 cairo_surface_observer_print (cairo_surface_t *abstract_surface,
 			      cairo_write_func_t write_func,
@@ -1987,6 +2092,16 @@ cairo_surface_observer_print (cairo_surface_t *abstract_surface,
     return _cairo_output_stream_destroy (stream);
 }
 
+/**
+ * cairo_surface_observer_elapsed:
+ * @abstract_surface: a #cairo_surface_observer_t
+ *
+ * Returns the total observation time.
+ *
+ * Returns: the elapsed time, in nanoseconds
+ *
+ * Since: 1.12
+ **/
 double
 cairo_surface_observer_elapsed (cairo_surface_t *abstract_surface)
 {
@@ -2002,6 +2117,18 @@ cairo_surface_observer_elapsed (cairo_surface_t *abstract_surface)
     return _cairo_time_to_ns (_cairo_observation_total_elapsed (&surface->log));
 }
 
+/**
+ * cairo_device_observer_print:
+ * @abstract_device: the observed #cairo_device_t
+ * @write_func: the write function
+ * @closure: data to pass to the @write_func
+ *
+ * Prints the device log using the given function.
+ *
+ * Returns: the status after the operation
+ *
+ * Since: 1.12
+ **/
 cairo_status_t
 cairo_device_observer_print (cairo_device_t *abstract_device,
 			     cairo_write_func_t write_func,
@@ -2023,6 +2150,16 @@ cairo_device_observer_print (cairo_device_t *abstract_device,
     return _cairo_output_stream_destroy (stream);
 }
 
+/**
+ * cairo_device_observer_elapsed:
+ * @abstract_device: the observed #cairo_device_t
+ *
+ * Returns the total elapsed time of the observation.
+ *
+ * Returns: the elapsed time, in nanoseconds.
+ *
+ * Since: 1.12
+ **/
 double
 cairo_device_observer_elapsed (cairo_device_t *abstract_device)
 {
@@ -2038,6 +2175,16 @@ cairo_device_observer_elapsed (cairo_device_t *abstract_device)
     return _cairo_time_to_ns (_cairo_observation_total_elapsed (&device->log));
 }
 
+/**
+ * cairo_device_observer_paint_elapsed:
+ * @abstract_device: the observed #cairo_device_t
+ *
+ * Returns the elapsed time of the paint operations.
+ *
+ * Returns: the elapsed time, in nanoseconds.
+ *
+ * Since: 1.12
+ **/
 double
 cairo_device_observer_paint_elapsed (cairo_device_t *abstract_device)
 {
@@ -2053,6 +2200,16 @@ cairo_device_observer_paint_elapsed (cairo_device_t *abstract_device)
     return _cairo_time_to_ns (device->log.paint.elapsed);
 }
 
+/**
+ * cairo_device_observer_mask_elapsed:
+ * @abstract_device: the observed #cairo_device_t
+ *
+ * Returns the elapsed time of the mask operations.
+ *
+ * Returns: the elapsed time, in nanoseconds
+ *
+ * Since: 1.12
+ **/
 double
 cairo_device_observer_mask_elapsed (cairo_device_t *abstract_device)
 {
@@ -2068,6 +2225,16 @@ cairo_device_observer_mask_elapsed (cairo_device_t *abstract_device)
     return _cairo_time_to_ns (device->log.mask.elapsed);
 }
 
+/**
+ * cairo_device_observer_fill_elapsed:
+ * @abstract_device: the observed #cairo_device_t
+ *
+ * Returns the elapsed time of the fill operations.
+ *
+ * Returns: the elapsed time, in nanoseconds.
+ *
+ * Since: 1.12
+ **/
 double
 cairo_device_observer_fill_elapsed (cairo_device_t *abstract_device)
 {
@@ -2083,6 +2250,16 @@ cairo_device_observer_fill_elapsed (cairo_device_t *abstract_device)
     return _cairo_time_to_ns (device->log.fill.elapsed);
 }
 
+/**
+ * cairo_device_observer_stroke_elapsed:
+ * @abstract_device: the observed #cairo_device_t
+ *
+ * Returns the elapsed time of the stroke operations.
+ *
+ * Returns: the elapsed time, in nanoseconds.
+ *
+ * Since: 1.12
+ **/
 double
 cairo_device_observer_stroke_elapsed (cairo_device_t *abstract_device)
 {
@@ -2098,6 +2275,16 @@ cairo_device_observer_stroke_elapsed (cairo_device_t *abstract_device)
     return _cairo_time_to_ns (device->log.stroke.elapsed);
 }
 
+/**
+ * cairo_device_observer_glyphs_elapsed:
+ * @abstract_device: the observed #cairo_device_t
+ *
+ * Returns the elapsed time of the glyph operations.
+ *
+ * Returns: the elapsed time, in nanoseconds.
+ *
+ * Since: 1.12
+ **/
 double
 cairo_device_observer_glyphs_elapsed (cairo_device_t *abstract_device)
 {
diff --git a/src/cairo-tee-surface.c b/src/cairo-tee-surface.c
index b5244df04..35baa9609 100644
--- a/src/cairo-tee-surface.c
+++ b/src/cairo-tee-surface.c
@@ -35,8 +35,22 @@
  *	Chris Wilson <chris@chris-wilson.co.uk>
  */
 
-/* This surface supports redirecting all its input to multiple surfaces.
- */
+/**
+ * SECTION:cairo-tee
+ * @Title: Tee surface
+ * @Short_Description: Redirect input to multiple surfaces
+ * @See_Also: #cairo_surface_t
+ *
+ * The "tee" surface supports redirecting all its input to multiple surfaces.
+ **/
+
+/**
+ * CAIRO_HAS_TEE_SURFACE:
+ *
+ * Defined if the tee surface backend is available.
+ *
+ * Since: 1.10
+ **/
 
 #include "cairoint.h"
 
@@ -420,6 +434,22 @@ static const cairo_surface_backend_t cairo_tee_surface_backend = {
     _cairo_tee_surface_show_text_glyphs
 };
 
+/**
+ * cairo_tee_surface_create:
+ * @primary: the primary #cairo_surface_t
+ *
+ * Creates a new "tee" surface.
+ *
+ * The @primary surface is used when querying surface options, like
+ * font options and extents.
+ *
+ * Operations performed on the tee surface will be replayed on any
+ * surface added to it.
+ *
+ * Returns: the newly created surface
+ *
+ * Since: 1.10
+ **/
 cairo_surface_t *
 cairo_tee_surface_create (cairo_surface_t *primary)
 {
@@ -445,6 +475,16 @@ cairo_tee_surface_create (cairo_surface_t *primary)
     return &surface->base;
 }
 
+/**
+ * cairo_tee_surface_add:
+ * @abstract_surface: a #cairo_tee_surface_t
+ * @target: the surface to add
+ *
+ * Adds a new target surface to the list of replicas of a
+ * tee surface.
+ *
+ * Since: 1.10
+ **/
 void
 cairo_tee_surface_add (cairo_surface_t *abstract_surface,
 		       cairo_surface_t *target)
@@ -482,6 +522,16 @@ cairo_tee_surface_add (cairo_surface_t *abstract_surface,
     }
 }
 
+/**
+ * cairo_tee_surface_remove:
+ * @abstract_surface: a #cairo_tee_surface_t
+ * @target: the surface to remove
+ *
+ * Removes the given surface from the list of replicas of a
+ * tee surface.
+ *
+ * Since: 1.10
+ **/
 void
 cairo_tee_surface_remove (cairo_surface_t *abstract_surface,
 			  cairo_surface_t *target)
@@ -530,6 +580,20 @@ cairo_tee_surface_remove (cairo_surface_t *abstract_surface,
     surface->replicas.num_elements--; /* XXX: cairo_array_remove()? */
 }
 
+/**
+ * cairo_tee_surface_index:
+ * @abstract_surface: a #cairo_tee_surface_t
+ * @index: the index of the replica to retrieve
+ *
+ * Retrieves the replica surface at the given index.
+ *
+ * The primary surface used to create the #cairo_tee_surface_t is
+ * always set at the zero index.
+ *
+ * Returns: the surface at the given index
+ *
+ * Since: 1.10
+ **/
 cairo_surface_t *
 cairo_tee_surface_index (cairo_surface_t *abstract_surface,
 			 unsigned int index)
diff --git a/src/cairo-tee.h b/src/cairo-tee.h
index 9125a3a4a..58264ffff 100644
--- a/src/cairo-tee.h
+++ b/src/cairo-tee.h
@@ -43,18 +43,18 @@
 CAIRO_BEGIN_DECLS
 
 cairo_public cairo_surface_t *
-cairo_tee_surface_create (cairo_surface_t *master);
+cairo_tee_surface_create (cairo_surface_t *primary);
 
 cairo_public void
-cairo_tee_surface_add (cairo_surface_t *surface,
+cairo_tee_surface_add (cairo_surface_t *abstract_surface,
 		       cairo_surface_t *target);
 
 cairo_public void
-cairo_tee_surface_remove (cairo_surface_t *surface,
+cairo_tee_surface_remove (cairo_surface_t *abstract_surface,
 			  cairo_surface_t *target);
 
 cairo_public cairo_surface_t *
-cairo_tee_surface_index (cairo_surface_t *surface,
+cairo_tee_surface_index (cairo_surface_t *abstract_surface,
 			 unsigned int index);
 
 CAIRO_END_DECLS
diff --git a/src/cairo-version.h b/src/cairo-version.h
index 3ac065f68..6efd7615d 100644
--- a/src/cairo-version.h
+++ b/src/cairo-version.h
@@ -2,7 +2,7 @@
 #define CAIRO_VERSION_H
 
 #define CAIRO_VERSION_MAJOR 1
-#define CAIRO_VERSION_MINOR 17
-#define CAIRO_VERSION_MICRO 9
+#define CAIRO_VERSION_MINOR 18
+#define CAIRO_VERSION_MICRO 1
 
 #endif
diff --git a/src/cairo-xcb-shm.c b/src/cairo-xcb-shm.c
index 763778ab2..5bc64a6cf 100644
--- a/src/cairo-xcb-shm.c
+++ b/src/cairo-xcb-shm.c
@@ -36,6 +36,15 @@
 
 #include "cairoint.h"
 
+/**
+ * CAIRO_HAS_XCB_SHM_FUNCTIONS:
+ *
+ * Defined if Cairo has SHM functions for XCB.
+ * This macro can be used to conditionally compile backend-specific code.
+ *
+ * Since: 1.10
+ **/
+
 #if CAIRO_HAS_XCB_SHM_FUNCTIONS
 
 #include "cairo-xcb-private.h"
diff --git a/src/cairo-xlib-surface.c b/src/cairo-xlib-surface.c
index b37b21bad..84d536209 100644
--- a/src/cairo-xlib-surface.c
+++ b/src/cairo-xlib-surface.c
@@ -47,6 +47,15 @@
 
 #include "cairoint.h"
 
+/**
+ * CAIRO_HAS_XLIB_XCB_FUNCTIONS:
+ *
+ * Defined if Cairo has support for XCB integration with Xlib.
+ * This macro can be used to conditionally compile backend-specific code.
+ *
+ * Since: 1.10
+ **/
+
 #if !CAIRO_HAS_XLIB_XCB_FUNCTIONS
 
 #include "cairo-xlib-private.h"
diff --git a/src/cairo.c b/src/cairo.c
index 12dbfb642..00521f264 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -2903,6 +2903,22 @@ cairo_copy_clip_rectangle_list (cairo_t *cr)
  **/
 
 /**
+ * CAIRO_TAG_CONTENT:
+ *
+ * Create a content tag.
+ *
+ * Since: 1.18
+ **/
+
+/**
+ * CAIRO_TAG_CONTENT_REF:
+ *
+ * Create a content reference tag.
+ *
+ * Since: 1.18
+ **/
+
+/**
  * cairo_tag_begin:
  * @cr: a cairo context
  * @tag_name: tag name
@@ -3885,7 +3901,7 @@ cairo_get_operator (cairo_t *cr)
 }
 
 #if 0
-/**
+/*
  * cairo_get_opacity:
  * @cr: a cairo context
  *
diff --git a/src/cairo.h b/src/cairo.h
index cd529c26e..89e4a070e 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -459,7 +459,6 @@ typedef enum _cairo_format {
  *
  * Since: 1.18
  **/
-#define CAIRO_HAS_DITHER
 typedef enum _cairo_dither {
     CAIRO_DITHER_NONE,
     CAIRO_DITHER_DEFAULT,
@@ -2401,6 +2400,16 @@ cairo_public cairo_surface_t *
 cairo_surface_create_observer (cairo_surface_t *target,
 			       cairo_surface_observer_mode_t mode);
 
+/**
+ * cairo_surface_observer_callback_t:
+ * @observer: the #cairo_surface_observer_t
+ * @target: the observed surface
+ * @data: closure used when adding the callback
+ *
+ * A generic callback function for surface operations.
+ *
+ * Since: 1.12
+ **/
 typedef void (*cairo_surface_observer_callback_t) (cairo_surface_t *observer,
 						   cairo_surface_t *target,
 						   void *data);
@@ -2441,34 +2450,34 @@ cairo_surface_observer_add_finish_callback (cairo_surface_t *abstract_surface,
 					    void *data);
 
 cairo_public cairo_status_t
-cairo_surface_observer_print (cairo_surface_t *surface,
+cairo_surface_observer_print (cairo_surface_t *abstract_surface,
 			      cairo_write_func_t write_func,
 			      void *closure);
 cairo_public double
-cairo_surface_observer_elapsed (cairo_surface_t *surface);
+cairo_surface_observer_elapsed (cairo_surface_t *abstract_surface);
 
 cairo_public cairo_status_t
-cairo_device_observer_print (cairo_device_t *device,
+cairo_device_observer_print (cairo_device_t *abstract_device,
 			     cairo_write_func_t write_func,
 			     void *closure);
 
 cairo_public double
-cairo_device_observer_elapsed (cairo_device_t *device);
+cairo_device_observer_elapsed (cairo_device_t *abstract_device);
 
 cairo_public double
-cairo_device_observer_paint_elapsed (cairo_device_t *device);
+cairo_device_observer_paint_elapsed (cairo_device_t *abstract_device);
 
 cairo_public double
-cairo_device_observer_mask_elapsed (cairo_device_t *device);
+cairo_device_observer_mask_elapsed (cairo_device_t *abstract_device);
 
 cairo_public double
-cairo_device_observer_fill_elapsed (cairo_device_t *device);
+cairo_device_observer_fill_elapsed (cairo_device_t *abstract_device);
 
 cairo_public double
-cairo_device_observer_stroke_elapsed (cairo_device_t *device);
+cairo_device_observer_stroke_elapsed (cairo_device_t *abstract_device);
 
 cairo_public double
-cairo_device_observer_glyphs_elapsed (cairo_device_t *device);
+cairo_device_observer_glyphs_elapsed (cairo_device_t *abstract_device);
 
 cairo_public cairo_surface_t *
 cairo_surface_reference (cairo_surface_t *surface);
diff --git a/src/check-doc-syntax.sh b/src/check-doc-syntax.sh
index 762a48429..57bbc91fd 100755
--- a/src/check-doc-syntax.sh
+++ b/src/check-doc-syntax.sh
@@ -28,7 +28,7 @@ enum_regexp="\([^%@']\|^\)\<\(FALSE\|TRUE\|NULL\|CAIRO_[0-9A-Z_]*\)\($\|[^(A-Za-
 if test "x$SGML_DOCS" = x; then
 	enum_regexp='^[^:]*:[/ ][*]\(\|[ \t].*\)'$enum_regexp\($\|[^:]\)
 fi
-if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep "$enum_regexp" | grep -v '#####'; then
+if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' -e '/\|\[/,/\]\|/d' | grep "$enum_regexp" | grep -v '#####'; then
 	stat=1
 	echo Error: some macros in the docs are not prefixed by percent sign.
 	echo Fix this by searching for the following regexp in the above files:
@@ -42,7 +42,7 @@ else
 	type_regexp='\(.'$type_regexp'\)\|\('$type_regexp'.\)'
 fi
 
-if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep -v "@Title" | grep "$type_regexp" | grep -v '#####'; then
+if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' -e '/\|\[/,/\]\|/d' | grep -v "@Title" | grep "$type_regexp" | grep -v '#####'; then
 	stat=1
 	echo Error: some type names in the docs are not prefixed by hash sign,
 	echo neither are the only token in the doc line followed by colon.
@@ -56,7 +56,7 @@ if test "x$SGML_DOCS" = x; then
 fi
 
 # We need to filter out gtk-doc markup errors for program listings.
-if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' | grep "$func_regexp" | grep -v '^[^:]*: [*] [a-z_0-9]*:$' | grep -v '#####'; then
+if echo $FILES | xargs grep . /dev/null | sed -e '/<programlisting>/,/<\/programlisting>/d' -e '/\|\[/,/\]\|/d' | grep "$func_regexp" | grep -v '^[^:]*: [*] [a-z_0-9]*:$' | grep -v '#####'; then
 	stat=1
 	echo Error: some function names in the docs are not followed by parentheses.
 	echo Fix this by searching for the following regexp in the above files: