Merge branch 'doc-fixes' into 'master'

More random doc fixes

See merge request cairo/cairo!437

15 files changed, 90 insertions, 49 deletions

diff --git a/doc/public/cairo-docs.xml b/doc/public/cairo-docs.xml
index 1fc031c1c..cc7c9aa04 100644
--- a/doc/public/cairo-docs.xml
+++ b/doc/public/cairo-docs.xml
@@ -43,11 +43,11 @@
     <xi:include href="xml/cairo-win32.xml"/>
     <xi:include href="xml/cairo-svg.xml"/>
     <xi:include href="xml/cairo-quartz.xml" />
-    <!--xi:include href="xml/cairo-quartz-image.xml"/-->
     <xi:include href="xml/cairo-xcb.xml"/>
     <xi:include href="xml/cairo-xlib.xml"/>
     <xi:include href="xml/cairo-xlib-xrender.xml"/>
     <xi:include href="xml/cairo-script.xml"/>
+    <xi:include href="xml/cairo-surface-observer.xml"/>
   </chapter>
   <chapter id="cairo-support">
     <title>Utilities</title>
diff --git a/doc/public/cairo-sections.txt b/doc/public/cairo-sections.txt
index 6a11c9b8a..5f53fc49c 100644
--- a/doc/public/cairo-sections.txt
+++ b/doc/public/cairo-sections.txt
@@ -166,6 +166,8 @@ CAIRO_HAS_QUARTZ_SURFACE
 cairo_quartz_surface_create
 cairo_quartz_surface_create_for_cg_context
 cairo_quartz_surface_get_cg_context
+cairo_quartz_image_surface_create
+cairo_quartz_image_surface_get_image
 </SECTION>
 
 <SECTION>
diff --git a/src/cairo-array.c b/src/cairo-array.c
index db7b6de7a..1c91b7c73 100644
--- a/src/cairo-array.c
+++ b/src/cairo-array.c
@@ -143,7 +143,6 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
 /**
  * _cairo_array_index:
  * @array: a #cairo_array_t
- * Returns: A pointer to the object stored at @index.
  *
  * If the resulting value is assigned to a pointer to an object of the same
  * element_size as initially passed to _cairo_array_init() then that
@@ -161,6 +160,8 @@ _cairo_array_truncate (cairo_array_t *array, unsigned int num_elements)
  *      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.
  **/
 void *
 _cairo_array_index (cairo_array_t *array, unsigned int index)
@@ -187,7 +188,6 @@ _cairo_array_index (cairo_array_t *array, unsigned int index)
 /**
  * _cairo_array_index_const:
  * @array: a #cairo_array_t
- * Returns: A pointer to the object stored at @index.
  *
  * If the resulting value is assigned to a pointer to an object of the same
  * element_size as initially passed to _cairo_array_init() then that
@@ -205,6 +205,8 @@ _cairo_array_index (cairo_array_t *array, unsigned int index)
  *      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.
  **/
 const void *
 _cairo_array_index_const (const cairo_array_t *array, unsigned int index)
@@ -330,9 +332,10 @@ _cairo_array_allocate (cairo_array_t	 *array,
 /**
  * _cairo_array_num_elements:
  * @array: a #cairo_array_t
- * Returns: The number of elements stored in @array.
  *
  * This space was left intentionally blank, but gtk-doc filled it.
+ *
+ * Returns: The number of elements stored in @array.
  **/
 unsigned int
 _cairo_array_num_elements (const cairo_array_t *array)
@@ -343,10 +346,11 @@ _cairo_array_num_elements (const cairo_array_t *array)
 /**
  * _cairo_array_size:
  * @array: a #cairo_array_t
- * Returns: The number of elements for which there is currently space
- * allocated in @array.
  *
  * This space was left intentionally blank, but gtk-doc filled it.
+ *
+ * Returns: The number of elements for which there is currently space
+ * allocated in @array.
  **/
 unsigned int
 _cairo_array_size (const cairo_array_t *array)
diff --git a/src/cairo-cache.c b/src/cairo-cache.c
index be1285a20..afdca984e 100644
--- a/src/cairo-cache.c
+++ b/src/cairo-cache.c
@@ -56,7 +56,6 @@ _cairo_cache_entry_is_non_zero (const void *entry)
  * @keys_equal: a function to return %TRUE if two keys are equal
  * @entry_destroy: destroy notifier for cache entries
  * @max_size: the maximum size for this cache
- * Returns: the newly created #cairo_cache_t
  *
  * Creates a new cache using the keys_equal() function to determine
  * the equality of entries.
@@ -84,6 +83,8 @@ _cairo_cache_entry_is_non_zero (const void *entry)
  * _cairo_cache_freeze() and _cairo_cache_thaw() calls can be
  * used to establish a window during which no automatic removal of
  * entries will occur.
+ *
+ * Returns: the newly created #cairo_cache_t
  **/
 cairo_status_t
 _cairo_cache_init (cairo_cache_t		*cache,
diff --git a/src/cairo-dwrite.h b/src/cairo-dwrite.h
index 630fcf280..b1ff718a0 100644
--- a/src/cairo-dwrite.h
+++ b/src/cairo-dwrite.h
@@ -51,7 +51,7 @@ cairo_public IDWriteRenderingParams *
 cairo_dwrite_font_face_get_rendering_params (cairo_font_face_t *font_face);
 
 cairo_public void
-cairo_dwrite_font_face_set_rendering_params (cairo_font_face_t *font_face, IDWriteRenderingParams *param);
+cairo_dwrite_font_face_set_rendering_params (cairo_font_face_t *font_face, IDWriteRenderingParams *params);
 
 cairo_public DWRITE_MEASURING_MODE
 cairo_dwrite_font_face_get_measuring_mode (cairo_font_face_t *font_face);
diff --git a/src/cairo-font-options.c b/src/cairo-font-options.c
index 361882ae5..fa3d3c4e1 100644
--- a/src/cairo-font-options.c
+++ b/src/cairo-font-options.c
@@ -662,7 +662,7 @@ cairo_font_options_get_variations (cairo_font_options_t *options)
 /**
  * cairo_font_options_set_color_mode:
  * @options: a #cairo_font_options_t
- * @font_color: the new color mode
+ * @color_mode: the new color mode
  *
  * Sets the color mode for the font options object. This controls
  * whether color fonts are to be rendered in color or as outlines.
diff --git a/src/cairo-pattern.c b/src/cairo-pattern.c
index d16ed2836..2c0ba31f8 100644
--- a/src/cairo-pattern.c
+++ b/src/cairo-pattern.c
@@ -3439,9 +3439,10 @@ use_bilinear(double x, double y, double t)
 /**
  * _cairo_pattern_analyze_filter:
  * @pattern: surface pattern
- * Returns: the optimized #cairo_filter_t to use with @pattern.
  *
  * Possibly optimize the filter to a simpler value depending on transformation
+ *
+ * Returns: the optimized #cairo_filter_t to use with @pattern.
  **/
 cairo_filter_t
 _cairo_pattern_analyze_filter (const cairo_pattern_t *pattern)
diff --git a/src/cairo-ps-surface.c b/src/cairo-ps-surface.c
index abc9407ee..381b4cf75 100644
--- a/src/cairo-ps-surface.c
+++ b/src/cairo-ps-surface.c
@@ -148,7 +148,7 @@ static char *ctime_r(const time_t *timep, char *buf)
  * ury]" that specifies the bounding box (in PS coordinates) of the
  * EPS graphics. The parameters are: lower left x, lower left y, upper
  * right x, upper right y. Normally the bbox data is identical to the
- * %%%BoundingBox data in the EPS file.
+ * \%\%\%BoundingBox data in the EPS file.
  *
  **/
 
diff --git a/src/cairo-quartz-image-surface.c b/src/cairo-quartz-image-surface.c
index 2c82ef1a3..e05523459 100644
--- a/src/cairo-quartz-image-surface.c
+++ b/src/cairo-quartz-image-surface.c
@@ -377,15 +377,27 @@ cairo_quartz_image_surface_create (cairo_surface_t *surface)
 }
 
 
+/**
+ * cairo_quartz_image_surface_get_image:
+ * @surface: a #cairo_surface_t
+ *
+ * Returns a #cairo_surface_t image surface that refers to the same bits
+ * as the image of the quartz surface.
+ *
+ * Return value: a #cairo_surface_t (owned by the quartz #cairo_surface_t),
+ * 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 *asurface)
+cairo_quartz_image_surface_get_image (cairo_surface_t *surface)
 {
-    cairo_quartz_image_surface_t *surface = (cairo_quartz_image_surface_t*) asurface;
+    cairo_quartz_image_surface_t *qsurface = (cairo_quartz_image_surface_t*) surface;
 
     /* Throw an error for a non-quartz surface */
-    if (! _cairo_surface_is_quartz (asurface)) {
+    if (! _cairo_surface_is_quartz (surface)) {
         return SURFACE_ERROR_TYPE_MISMATCH;
     }
 
-    return (cairo_surface_t*) surface->imageSurface;
+    return (cairo_surface_t*) qsurface->imageSurface;
 }
diff --git a/src/cairo-scaled-font.c b/src/cairo-scaled-font.c
index 415b45f78..75640f723 100755
--- a/src/cairo-scaled-font.c
+++ b/src/cairo-scaled-font.c
@@ -2660,6 +2660,8 @@ _cairo_scaled_glyph_set_path (cairo_scaled_glyph_t *scaled_glyph,
  * @recording_surface: The recording surface
  * @foreground_color: The foreground color that was used to record the
  * 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,
@@ -2691,6 +2693,8 @@ _cairo_scaled_glyph_set_recording_surface (cairo_scaled_glyph_t *scaled_glyph,
  * @foreground_marker_color: The foreground color that was used to
  * substitute the foreground_marker, or NULL if foreground_marker not
  * 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,
diff --git a/src/cairo-surface-observer.c b/src/cairo-surface-observer.c
index 9c4432e24..bf29d4219 100644
--- a/src/cairo-surface-observer.c
+++ b/src/cairo-surface-observer.c
@@ -54,6 +54,15 @@
 #include "cairo-script-private.h"
 #endif
 
+/**
+ * SECTION:cairo-surface-observer
+ * @Title: Surface Observer
+ * @Short_Description: Observing other surfaces
+ * @See_Also: #cairo_surface_t
+ *
+ * A surface that exists solely to watch another is doing.
+ */
+
 static const cairo_surface_backend_t _cairo_surface_observer_backend;
 
 /* observation/stats */
diff --git a/src/cairo-svg.h b/src/cairo-svg.h
index 5328cb583..7745eec90 100644
--- a/src/cairo-svg.h
+++ b/src/cairo-svg.h
@@ -73,9 +73,9 @@ typedef enum _cairo_svg_version {
  * lengths in the SVG specification.
  *
  * See also:
- * https://www.w3.org/TR/SVG/coords.html#Units
- * https://www.w3.org/TR/SVG/types.html#DataTypeLength
- * https://www.w3.org/TR/css-values-3/#lengths
+ * - [SVG Units](https://www.w3.org/TR/SVG/coords.html#Units)
+ * - [SVG Types](https://www.w3.org/TR/SVG/types.html#DataTypeLength)
+ * - [CSS Length](https://www.w3.org/TR/css-values-3/#lengths)
  *
  * Since: 1.16
  **/
diff --git a/src/cairo.c b/src/cairo.c
index bff1b86af..3d4fea601 100644
--- a/src/cairo.c
+++ b/src/cairo.c
@@ -1166,9 +1166,8 @@ cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
  * cairo_set_line_width() and ignore this note.
  *
  * As with the other stroke parameters, the current line width is
- * examined by cairo_stroke(), cairo_stroke_extents(), and
- * cairo_stroke_to_path(), but does not have any effect during path
- * construction.
+ * examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
+ * any effect during path construction.
  *
  * The default line width value is 2.0.
  *
@@ -1242,9 +1241,8 @@ slim_hidden_def (cairo_set_hairline);
  * styles are drawn.
  *
  * As with the other stroke parameters, the current line cap style is
- * examined by cairo_stroke(), cairo_stroke_extents(), and
- * cairo_stroke_to_path(), but does not have any effect during path
- * construction.
+ * examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
+ * any effect during path construction.
  *
  * The default line cap style is %CAIRO_LINE_CAP_BUTT.
  *
@@ -1274,9 +1272,8 @@ slim_hidden_def (cairo_set_line_cap);
  * styles are drawn.
  *
  * As with the other stroke parameters, the current line join style is
- * examined by cairo_stroke(), cairo_stroke_extents(), and
- * cairo_stroke_to_path(), but does not have any effect during path
- * construction.
+ * examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
+ * any effect during path construction.
  *
  * The default line join style is %CAIRO_LINE_JOIN_MITER.
  *
@@ -1411,9 +1408,8 @@ cairo_get_dash (cairo_t *cr,
  * converted to a bevel.
  *
  * As with the other stroke parameters, the current line miter limit is
- * examined by cairo_stroke(), cairo_stroke_extents(), and
- * cairo_stroke_to_path(), but does not have any effect during path
- * construction.
+ * examined by cairo_stroke(), and cairo_stroke_extents(), but does not have
+ * any effect during path construction.
  *
  * The default miter limit value is 10.0, which will convert joins
  * with interior angles less than 11 degrees to bevels instead of
@@ -2941,7 +2937,7 @@ cairo_copy_clip_rectangle_list (cairo_t *cr)
  * CAIRO_TAG_DEST:
  *
  * Create a destination for a hyperlink. Destination tag attributes
- * are detailed at [Destinations][dests].
+ * are detailed at [Destinations][dest].
  *
  * Since: 1.16
  **/
@@ -2950,7 +2946,7 @@ cairo_copy_clip_rectangle_list (cairo_t *cr)
  * CAIRO_TAG_LINK:
  *
  * Create hyperlink. Link tag attributes are detailed at
- * [Links][links].
+ * [Links][link].
  *
  * Since: 1.16
  **/
@@ -4044,7 +4040,7 @@ slim_hidden_def (cairo_has_current_point);
  * cairo_move_to(), cairo_line_to(), cairo_curve_to(),
  * cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
  * cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
- * cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
+ * cairo_text_path(), cairo_glyph_path().
  *
  * Some functions use and alter the current point but do not
  * otherwise change current path:
diff --git a/src/cairo.h b/src/cairo.h
index 78a958476..eef4c442b 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -295,6 +295,7 @@ typedef struct _cairo_user_data_key {
  * @CAIRO_STATUS_WIN32_GDI_ERROR: error occurred in the Windows Graphics Device Interface (Since 1.16)
  * @CAIRO_STATUS_TAG_ERROR: invalid tag name, attributes, or nesting (Since 1.16)
  * @CAIRO_STATUS_DWRITE_ERROR: error occurred in the Windows Direct Write API (Since 1.18)
+ * @CAIRO_STATUS_SVG_FONT_ERROR: error occurred in OpenType-SVG font rendering (Since 1.18)
  * @CAIRO_STATUS_LAST_STATUS: this is a special value indicating the number of
  *   status values defined in this enumeration.  When using this value, note
  *   that the version of cairo at run-time may have additional status values
@@ -2448,26 +2449,37 @@ cairo_surface_status (cairo_surface_t *surface);
  * @CAIRO_SURFACE_TYPE_PS: The surface is of type ps, since 1.2
  * @CAIRO_SURFACE_TYPE_XLIB: The surface is of type xlib, since 1.2
  * @CAIRO_SURFACE_TYPE_XCB: The surface is of type xcb, since 1.2
- * @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz, since 1.2
+ * @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz, since 1.2, deprecated 1.18
+ *   (glitz support have been removed, this surface type will never be set by cairo)
  * @CAIRO_SURFACE_TYPE_QUARTZ: The surface is of type quartz, since 1.2
  * @CAIRO_SURFACE_TYPE_WIN32: The surface is of type win32, since 1.2
- * @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos, since 1.2
- * @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb, since 1.2
+ * @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos, since 1.2, deprecated 1.18
+ *   (beos support have been removed, this surface type will never be set by cairo)
+ * @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb, since 1.2, deprecated 1.18
+ *   (directfb support have been removed, this surface type will never be set by cairo)
  * @CAIRO_SURFACE_TYPE_SVG: The surface is of type svg, since 1.2
- * @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2, since 1.4
+ * @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2, since 1.4, deprecated 1.18
+ *   (os2 support have been removed, this surface type will never be set by cairo)
  * @CAIRO_SURFACE_TYPE_WIN32_PRINTING: The surface is a win32 printing surface, since 1.6
  * @CAIRO_SURFACE_TYPE_QUARTZ_IMAGE: The surface is of type quartz_image, since 1.6
  * @CAIRO_SURFACE_TYPE_SCRIPT: The surface is of type script, since 1.10
- * @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10
+ * @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10, deprecated 1.18
+ *   (Ot support have been removed, this surface type will never be set by cairo)
  * @CAIRO_SURFACE_TYPE_RECORDING: The surface is of type recording, since 1.10
- * @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10
- * @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10
- * @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10
+ * @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10, deprecated 1.18
+ *   (OpenVG support have been removed, this surface type will never be set by cairo)
+ * @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10, deprecated 1.18
+ *   (OpenGL support have been removed, this surface type will never be set by cairo)
+ * @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10, deprecated 1.18
+ *   (DRM support have been removed, this surface type will never be set by cairo)
  * @CAIRO_SURFACE_TYPE_TEE: The surface is of type 'tee' (a multiplexing surface), since 1.10
  * @CAIRO_SURFACE_TYPE_XML: The surface is of type XML (for debugging), since 1.10
+ * @CAIRO_SURFACE_TYPE_SKIA: The surface is of type Skia, since 1.10, deprecated 1.18
+ *   (Skia support have been removed, this surface type will never be set by cairo)
  * @CAIRO_SURFACE_TYPE_SUBSURFACE: The surface is a subsurface created with
  *   cairo_surface_create_for_rectangle(), since 1.10
- * @CAIRO_SURFACE_TYPE_COGL: This surface is of type Cogl, since 1.12
+ * @CAIRO_SURFACE_TYPE_COGL: This surface is of type Cogl, since 1.12, deprecated 1.18
+ *   (Cogl support have been removed, this surface type will never be set by cairo)
  *
  * #cairo_surface_type_t is used to describe the type of a given
  * surface. The surface types are also known as "backends" or "surface
diff --git a/src/win32/cairo-dwrite-font.cpp b/src/win32/cairo-dwrite-font.cpp
index 8346e4856..994889e21 100644
--- a/src/win32/cairo-dwrite-font.cpp
+++ b/src/win32/cairo-dwrite-font.cpp
@@ -923,7 +923,7 @@ _cairo_dwrite_scaled_font_init_glyph_color_surface(cairo_dwrite_scaled_font_t *s
     RefPtr<IDWriteColorGlyphRunEnumerator1> run_enumerator;
     HRESULT hr;
 
-    /**
+    /*
      * We transform by the inverse transformation here. This will put our glyph
      * locations in the space in which we draw. Which is later transformed by
      * the transformation matrix that we use. This will transform the
@@ -932,7 +932,7 @@ _cairo_dwrite_scaled_font_init_glyph_color_surface(cairo_dwrite_scaled_font_t *s
      */
     cairo_matrix_transform_point(&scaled_font->mat_inverse, &x, &y);
     offset.advanceOffset = (FLOAT)x;
-    /** Y-axis is inverted */
+    /* Y-axis is inverted */
     offset.ascenderOffset = -(FLOAT)y;
 
     run.fontFace = dwrite_font_face->dwriteface;
@@ -1205,7 +1205,7 @@ _cairo_dwrite_scaled_font_init_glyph_surface(cairo_dwrite_scaled_font_t *scaled_
     if (status)
 	goto FAIL;
 
-    /**
+    /*
      * We transform by the inverse transformation here. This will put our glyph
      * locations in the space in which we draw. Which is later transformed by
      * the transformation matrix that we use. This will transform the
@@ -1214,7 +1214,7 @@ _cairo_dwrite_scaled_font_init_glyph_surface(cairo_dwrite_scaled_font_t *scaled_
      */
     cairo_matrix_transform_point(&scaled_font->mat_inverse, &x, &y);
     offset.advanceOffset = (FLOAT)x;
-    /** Y-axis is inverted */
+    /* Y-axis is inverted */
     offset.ascenderOffset = -(FLOAT)y;
 
     area.top = 0;
@@ -1573,7 +1573,7 @@ _dwrite_draw_glyphs_to_gdi_surface_gdi(cairo_win32_surface_t *surface,
     else
 	params = DWriteFactory::DefaultRenderingParams();
 
-    /**
+    /*
      * We set the number of pixels per DIP to 1.0. This is because we always want
      * to draw in device pixels, and not device independent pixels. On high DPI
      * systems this value will be higher than 1.0 and automatically upscale
@@ -1716,7 +1716,7 @@ _cairo_dwrite_show_glyphs_on_surface(void			*surface,
 	    largestY = (INT32)glyphs[i].y;
 	}
     }
-    /**
+    /*
      * Here we try to get a rough estimate of the area that this glyph run will
      * cover on the surface. Since we use GDI interop to draw we will be copying
      * data around the size of the area of the surface that we map. We will want
@@ -1776,7 +1776,7 @@ _cairo_dwrite_show_glyphs_on_surface(void			*surface,
 	    double x = glyphs[i].x - fontArea.left + EPSILON;
 	    double y = glyphs[i].y - fontArea.top;
 	    cairo_matrix_transform_point(&dwritesf->mat_inverse, &x, &y);
-	    /**
+	    /*
 	     * Since we will multiply by our ctm matrix later for rotation effects
 	     * and such, adjust positions by the inverse matrix now. The Y-axis
 	     * is inverted so the offset becomes negative.