[pango/gi-docs: 15/45] docs: Port PangoCairo apis to the new doc format

[Matthias Clasen <matthiasc src gnome org>]

commit 9b1b9f9530f47bfc7293f78621f284e2f793d7a7
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Feb 15 01:19:06 2021 -0500

    docs: Port PangoCairo apis to the new doc format
    
    Replace gtk-doc'isms and use gi-docgen links instead.
    
    Cross-gir links are still an open issue.

 pango/pangocairo-context.c | 106 +++++++++++++++++++++++----------------------
 pango/pangocairo-font.c    |  14 +++---
 pango/pangocairo-fontmap.c |  97 +++++++++++++++++++++--------------------
 pango/pangocairo-render.c  |  52 +++++++++++-----------
 4 files changed, 136 insertions(+), 133 deletions(-)
---
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index 1b8bfbba..b75c64d6 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -158,16 +158,16 @@ _pango_cairo_update_context (cairo_t      *cr,
 /**
  * pango_cairo_update_context:
  * @cr: a Cairo context
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  *
- * Updates a #PangoContext previously created for use with Cairo to
+ * Updates a `PangoContext` previously created for use with Cairo to
  * match the current transformation and target surface of a Cairo
  * context. If any layouts have been created for the context,
  * it's necessary to call pango_layout_context_changed() on those
  * layouts.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_update_context (cairo_t      *cr,
                            PangoContext *context)
@@ -180,18 +180,18 @@ pango_cairo_update_context (cairo_t      *cr,
 
 /**
  * pango_cairo_context_set_resolution:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  * @dpi: the resolution in "dots per inch". (Physical inches aren't actually
  *   involved; the terminology is conventional.) A 0 or negative value
  *   means to use the resolution from the font map.
  *
  * Sets the resolution for the context. This is a scale factor between
- * points specified in a #PangoFontDescription and Cairo units. The
+ * points specified in a `PangoFontDescription` and Cairo units. The
  * default value is 96, meaning that a 10 point font will be 13
  * units high. (10 * 96. / 72. = 13.3).
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_context_set_resolution (PangoContext *context,
                                    double        dpi)
@@ -202,15 +202,16 @@ pango_cairo_context_set_resolution (PangoContext *context,
 
 /**
  * pango_cairo_context_get_resolution:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  *
- * Gets the resolution for the context. See pango_cairo_context_set_resolution()
+ * Gets the resolution for the context.
+ * See [method@PangoCairo.Context.set_resolution]
  *
  * Return value: the resolution in "dots per inch". A negative value will
- *  be returned if no resolution has previously been set.
+ *   be returned if no resolution has previously been set.
  *
  * Since: 1.10
- **/
+ */
 double
 pango_cairo_context_get_resolution (PangoContext *context)
 {
@@ -224,12 +225,12 @@ pango_cairo_context_get_resolution (PangoContext *context)
 
 /**
  * pango_cairo_context_set_font_options:
- * @context: a #PangoContext, from a pangocairo font map
- * @options: (nullable): a #cairo_font_options_t, or %NULL to unset
- *           any previously set options. A copy is made.
+ * @context: a `PangoContext`, from a pangocairo font map
+ * @options: (nullable): a `cairo_font_options_t`, or %NULL to unset
+ *   any previously set options. A copy is made.
  *
  * Sets the font options used when rendering text with this context.
- * These options override any options that pango_cairo_update_context()
+ * These options override any options that [func@update_context]
  * derives from the target surface.
  *
  * Since: 1.10
@@ -278,18 +279,19 @@ pango_cairo_context_set_font_options (PangoContext               *context,
 
 /**
  * pango_cairo_context_get_font_options:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  *
  * Retrieves any font rendering options previously set with
- * pango_cairo_context_set_font_options(). This function does not report options
- * that are derived from the target surface by pango_cairo_update_context()
+ * [method@PangoCairo.Context.set_font_options]. This function
+ * does not report options that are derived from the target
+ * surface by [func@update_context].
  *
  * Return value: (nullable): the font options previously set on the
  *   context, or %NULL if no options have been set. This value is
  *   owned by the context and must not be modified or freed.
  *
  * Since: 1.10
- **/
+ */
 const cairo_font_options_t *
 pango_cairo_context_get_font_options (PangoContext *context)
 {
@@ -307,15 +309,15 @@ pango_cairo_context_get_font_options (PangoContext *context)
 
 /**
  * _pango_cairo_context_merge_font_options:
- * @context: a #PangoContext
- * @options: a #cairo_font_options_t
+ * @context: a `PangoContext`
+ * @options: a `cairo_font_options_t`
  *
  * Merge together options from the target surface and explicitly set
  * on the context.
  *
  * Return value: the combined set of font options. This value is owned
- * by the context and must not be modified or freed.
- **/
+ *   by the context and must not be modified or freed.
+ */
 const cairo_font_options_t *
 _pango_cairo_context_get_merged_font_options (PangoContext *context)
 {
@@ -336,7 +338,7 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context)
 
 /**
  * pango_cairo_context_set_shape_renderer:
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  * @func: (nullable): Callback function for rendering attributes of
  *        type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering.
  * @data: User data that will be passed to @func.
@@ -344,7 +346,7 @@ _pango_cairo_context_get_merged_font_options (PangoContext *context)
  *           context is freed to release @data, or %NULL.
  *
  * Sets callback function for context to use for rendering attributes
- * of type %PANGO_ATTR_SHAPE.  See #PangoCairoShapeRendererFunc for
+ * of type %PANGO_ATTR_SHAPE.  See `PangoCairoShapeRendererFunc` for
  * details.
  *
  * Since: 1.18
@@ -371,26 +373,26 @@ pango_cairo_context_set_shape_renderer (PangoContext                *context,
 
 /**
  * pango_cairo_context_get_shape_renderer: (skip)
- * @context: a #PangoContext, from a pangocairo font map
+ * @context: a `PangoContext`, from a pangocairo font map
  * @data: Pointer to #gpointer to return user data
  *
  * Sets callback function for context to use for rendering attributes
- * of type %PANGO_ATTR_SHAPE.  See #PangoCairoShapeRendererFunc for
+ * of type %PANGO_ATTR_SHAPE.  See `PangoCairoShapeRendererFunc` for
  * details.
  *
  * Retrieves callback function and associated user data for rendering
  * attributes of type %PANGO_ATTR_SHAPE as set by
- * pango_cairo_context_set_shape_renderer(), if any.
+ * [method@PangoCairo.Context.set_shape_renderer], if any.
  *
- * Return value: (transfer none) (nullable): the shape rendering callback previously
- *   set on the context, or %NULL if no shape rendering callback have
- *   been set.
+ * Return value: (transfer none) (nullable): the shape rendering callback
+ *   previously set on the context, or %NULL if no shape rendering callback
+ *   have been set.
  *
  * Since: 1.18
  */
 PangoCairoShapeRendererFunc
-pango_cairo_context_get_shape_renderer (PangoContext                *context,
-                                       gpointer                    *data)
+pango_cairo_context_get_shape_renderer (PangoContext *context,
+                                        gpointer     *data)
 {
   PangoCairoContextInfo *info;
 
@@ -417,19 +419,19 @@ pango_cairo_context_get_shape_renderer (PangoContext                *context,
  * @cr: a Cairo context
  *
  * Creates a context object set up to match the current transformation
- * and target surface of the Cairo context.  This context can then be
+ * and target surface of the Cairo context. This context can then be
  * used to create a layout using pango_layout_new().
  *
  * This function is a convenience function that creates a context using
- * the default font map, then updates it to @cr.  If you just need to
- * create a layout for use with @cr and do not need to access #PangoContext
- * directly, you can use pango_cairo_create_layout() instead.
+ * the default font map, then updates it to @cr. If you just need to
+ * create a layout for use with @cr and do not need to access `PangoContext`
+ * directly, you can use [func@create_layout] instead.
  *
- * Return value: (transfer full): the newly created #PangoContext. Free with
- *   g_object_unref().
+ * Return value: (transfer full): the newly created `PangoContext`.
+ *   Free with g_object_unref().
  *
  * Since: 1.22
- **/
+ */
 PangoContext *
 pango_cairo_create_context (cairo_t *cr)
 {
@@ -450,24 +452,24 @@ pango_cairo_create_context (cairo_t *cr)
  * @cr: a Cairo context
  *
  * Creates a layout object set up to match the current transformation
- * and target surface of the Cairo context.  This layout can then be
+ * and target surface of the Cairo context. This layout can then be
  * used for text measurement with functions like
  * pango_layout_get_size() or drawing with functions like
- * pango_cairo_show_layout(). If you change the transformation
- * or target surface for @cr, you need to call pango_cairo_update_layout()
+ * [func@show_layout]. If you change the transformation or target
+ * surface for @cr, you need to call [func@update_layout].
  *
  * This function is the most convenient way to use Cairo with Pango,
  * however it is slightly inefficient since it creates a separate
- * #PangoContext object for each layout. This might matter in an
+ * `PangoContext` object for each layout. This might matter in an
  * application that was laying out large amounts of text.
  *
- * Return value: (transfer full): the newly created #PangoLayout. Free with
- *   g_object_unref().
+ * Return value: (transfer full): the newly created `PangoLayout`.
+ *   Free with g_object_unref().
  *
  * Since: 1.10
- **/
+ */
 PangoLayout *
-pango_cairo_create_layout  (cairo_t *cr)
+pango_cairo_create_layout (cairo_t *cr)
 {
   PangoContext *context;
   PangoLayout *layout;
@@ -484,14 +486,14 @@ pango_cairo_create_layout  (cairo_t *cr)
 /**
  * pango_cairo_update_layout:
  * @cr: a Cairo context
- * @layout: a #PangoLayout, from pango_cairo_create_layout()
+ * @layout: a `PangoLayout`, from [func@create_layout]
  *
- * Updates the private #PangoContext of a #PangoLayout created with
- * pango_cairo_create_layout() to match the current transformation
- * and target surface of a Cairo context.
+ * Updates the private `PangoContext` of a `PangoLayout` created with
+ * [func@create_layout] to match the current transformation and target
+ * surface of a Cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_update_layout (cairo_t     *cr,
                           PangoLayout *layout)
diff --git a/pango/pangocairo-font.c b/pango/pangocairo-font.c
index 1cadd005..c4155f68 100644
--- a/pango/pangocairo-font.c
+++ b/pango/pangocairo-font.c
@@ -137,17 +137,17 @@ done:
 
 /**
  * pango_cairo_font_get_scaled_font:
- * @font: a #PangoFont from a #PangoCairoFontMap
+ * @font: a `PangoFont` from a `PangoCairoFontMap`
  *
- * Gets the #cairo_scaled_font_t used by @font.
+ * Gets the `cairo_scaled_font_t` used by @font.
  * The scaled font can be referenced and kept using
  * cairo_scaled_font_reference().
  *
- * Return value: (transfer none) (nullable): the #cairo_scaled_font_t used by @font,
- *               or %NULL if @font is %NULL.
+ * Return value: (transfer none) (nullable): the `cairo_scaled_font_t`
+ *   used by @font, or %NULL if @font is %NULL.
  *
  * Since: 1.18
- **/
+ */
 cairo_scaled_font_t *
 pango_cairo_font_get_scaled_font (PangoCairoFont *cfont)
 {
@@ -163,14 +163,14 @@ pango_cairo_font_get_scaled_font (PangoCairoFont *cfont)
 
 /**
  * _pango_cairo_font_install:
- * @font: a #PangoCairoFont
+ * @font: a `PangoCairoFont`
  * @cr: a #cairo_t
  *
  * Makes @font the current font for rendering in the specified
  * Cairo context.
  *
  * Return value: %TRUE if font was installed successfully, %FALSE otherwise.
- **/
+ */
 gboolean
 _pango_cairo_font_install (PangoFont *font,
                           cairo_t   *cr)
diff --git a/pango/pangocairo-fontmap.c b/pango/pangocairo-fontmap.c
index 120ccb89..5f24ec93 100644
--- a/pango/pangocairo-fontmap.c
+++ b/pango/pangocairo-fontmap.c
@@ -47,29 +47,29 @@ pango_cairo_font_map_default_init (PangoCairoFontMapIface *iface)
 /**
  * pango_cairo_font_map_new:
  *
- * Creates a new #PangoCairoFontMap object; a fontmap is used
+ * Creates a new `PangoCairoFontMap` object; a fontmap is used
  * to cache information about available fonts, and holds
  * certain global parameters such as the resolution.
- * In most cases, you can use pango_cairo_font_map_get_default()
+ * In most cases, you can use `func@font_map_get_default]
  * instead.
  *
  * Note that the type of the returned object will depend
  * on the particular font backend Cairo was compiled to use;
- * You generally should only use the #PangoFontMap and
- * #PangoCairoFontMap interfaces on the returned object.
+ * You generally should only use the `PangoFontMap` and
+ * `PangoCairoFontMap` interfaces on the returned object.
  *
  * You can override the type of backend returned by using an
- * environment variable %PANGOCAIRO_BACKEND.  Supported types,
+ * environment variable %PANGOCAIRO_BACKEND. Supported types,
  * based on your build, are fc (fontconfig), win32, and coretext.
  * If requested type is not available, NULL is returned. Ie.
  * this is only useful for testing, when at least two backends
  * are compiled in.
  *
- * Return value: (transfer full): the newly allocated #PangoFontMap,
- *               which should be freed with g_object_unref().
+ * Return value: (transfer full): the newly allocated `PangoFontMap`,
+ *   which should be freed with g_object_unref().
  *
  * Since: 1.10
- **/
+ */
 PangoFontMap *
 pango_cairo_font_map_new (void)
 {
@@ -110,20 +110,19 @@ pango_cairo_font_map_new (void)
  * pango_cairo_font_map_new_for_font_type:
  * @fonttype: desired #cairo_font_type_t
  *
- * Creates a new #PangoCairoFontMap object of the type suitable
+ * Creates a new `PangoCairoFontMap` object of the type suitable
  * to be used with cairo font backend of type @fonttype.
  *
- * In most cases one should simply use @pango_cairo_font_map_new(),
- * or in fact in most of those cases, just use
- * @pango_cairo_font_map_get_default().
+ * In most cases one should simply use [func@font_map_new], or
+ * in fact in most of those cases, just use [func@font_map_get_default].
  *
  * Return value: (transfer full) (nullable): the newly allocated
- *               #PangoFontMap of suitable type which should be freed
- *               with g_object_unref(), or %NULL if the requested
- *               cairo font backend is not supported / compiled in.
+ *   `PangoFontMap` of suitable type which should be freed with
+ *   g_object_unref(), or %NULL if the requested cairo font backend
+ *   is not supported / compiled in.
  *
  * Since: 1.18
- **/
+ */
 PangoFontMap *
 pango_cairo_font_map_new_for_font_type (cairo_font_type_t fonttype)
 {
@@ -151,27 +150,28 @@ static GPrivate default_font_map = G_PRIVATE_INIT (g_object_unref); /* MT-safe *
 /**
  * pango_cairo_font_map_get_default:
  *
- * Gets a default #PangoCairoFontMap to use with Cairo.
+ * Gets a default `PangoCairoFontMap` to use with Cairo.
  *
- * Note that the type of the returned object will depend
- * on the particular font backend Cairo was compiled to use;
- * You generally should only use the #PangoFontMap and
- * #PangoCairoFontMap interfaces on the returned object.
+ * Note that the type of the returned object will depend on the
+ * particular font backend Cairo was compiled to use; you generally
+ * should only use the `PangoFontMap` and `PangoCairoFontMap`
+ * interfaces on the returned object.
  *
  * The default Cairo fontmap can be changed by using
- * pango_cairo_font_map_set_default().  This can be used to
- * change the Cairo font backend that the default fontmap
- * uses for example.
+ * [method@PangoCairo.FontMap.set_default]. This can be used to
+ * change the Cairo font backend that the default fontmap uses
+ * for example.
  *
  * Note that since Pango 1.32.6, the default fontmap is per-thread.
- * Each thread gets its own default fontmap.  In this way,
- * PangoCairo can be used safely from multiple threads.
+ * Each thread gets its own default fontmap. In this way, PangoCairo
+ * can be used safely from multiple threads.
  *
  * Return value: (transfer none): the default PangoCairo fontmap
- *  for the current thread. This object is owned by Pango and must not be freed.
+ *  for the current thread. This object is owned by Pango and must
+ *  not be freed.
  *
  * Since: 1.10
- **/
+ */
 PangoFontMap *
 pango_cairo_font_map_get_default (void)
 {
@@ -190,24 +190,24 @@ pango_cairo_font_map_get_default (void)
  * pango_cairo_font_map_set_default:
  * @fontmap: (nullable): The new default font map, or %NULL
  *
- * Sets a default #PangoCairoFontMap to use with Cairo.
+ * Sets a default `PangoCairoFontMap` to use with Cairo.
  *
  * This can be used to change the Cairo font backend that the
- * default fontmap uses for example.  The old default font map
+ * default fontmap uses for example. The old default font map
  * is unreffed and the new font map referenced.
  *
  * Note that since Pango 1.32.6, the default fontmap is per-thread.
  * This function only changes the default fontmap for
- * the current thread.  Default fontmaps of existing threads
+ * the current thread. Default fontmaps of existing threads
  * are not changed. Default fontmaps of any new threads will
- * still be created using pango_cairo_font_map_new().
+ * still be created using [func@font_map_new].
  *
  * A value of %NULL for @fontmap will cause the current default
- * font map to be released and a new default font
- * map to be created on demand, using pango_cairo_font_map_new().
+ * font map to be released and a new default font map to be created
+ * on demand, using [func@font_map_new].
  *
  * Since: 1.22
- **/
+ */
 void
 pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap)
 {
@@ -221,20 +221,20 @@ pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap)
 
 /**
  * pango_cairo_font_map_set_resolution:
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
  * @dpi: the resolution in "dots per inch". (Physical inches aren't actually
  *   involved; the terminology is conventional.)
  *
  * Sets the resolution for the fontmap. This is a scale factor between
- * points specified in a #PangoFontDescription and Cairo units. The
+ * points specified in a `PangoFontDescription` and Cairo units. The
  * default value is 96, meaning that a 10 point font will be 13
  * units high. (10 * 96. / 72. = 13.3).
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap,
-                                    double             dpi)
+                                     double             dpi)
 {
   g_return_if_fail (PANGO_IS_CAIRO_FONT_MAP (fontmap));
 
@@ -243,9 +243,10 @@ pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap,
 
 /**
  * pango_cairo_font_map_get_resolution:
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
  *
- * Gets the resolution for the fontmap. See pango_cairo_font_map_set_resolution()
+ * Gets the resolution for the fontmap.
+ * See [method@PangoCairo.FontMap.set_resolution].
  *
  * Return value: the resolution in "dots per inch"
  *
@@ -261,16 +262,16 @@ pango_cairo_font_map_get_resolution (PangoCairoFontMap *fontmap)
 
 /**
  * pango_cairo_font_map_create_context: (skip)
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
  *
- * Create a #PangoContext for the given fontmap.
+ * Create a `PangoContext` for the given fontmap.
  *
  * Return value: the newly created context; free with g_object_unref().
  *
  * Since: 1.10
  *
  * Deprecated: 1.22: Use pango_font_map_create_context() instead.
- **/
+ */
 PangoContext *
 pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap)
 {
@@ -281,14 +282,14 @@ pango_cairo_font_map_create_context (PangoCairoFontMap *fontmap)
 
 /**
  * pango_cairo_font_map_get_font_type:
- * @fontmap: a #PangoCairoFontMap
+ * @fontmap: a `PangoCairoFontMap`
  *
- * Gets the type of Cairo font backend that @fontmap uses.  
+ * Gets the type of Cairo font backend that @fontmap uses.
  *
- * Return value: the #cairo_font_type_t cairo font backend type
+ * Return value: the `cairo_font_type_t` cairo font backend type
  *
  * Since: 1.18
- **/
+ */
 cairo_font_type_t
 pango_cairo_font_map_get_font_type (PangoCairoFontMap *fontmap)
 {
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 6f017fee..47beb100 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -1041,15 +1041,15 @@ _pango_cairo_do_error_underline (cairo_t *cr,
 /**
  * pango_cairo_show_glyph_string:
  * @cr: a Cairo context
- * @font: a #PangoFont from a #PangoCairoFontMap
- * @glyphs: a #PangoGlyphString
+ * @font: a `PangoFont` from a `PangoCairoFontMap`
+ * @glyphs: a `PangoGlyphString`
  *
  * Draws the glyphs in @glyphs in the specified cairo context.
  * The origin of the glyphs (the left edge of the baseline) will
  * be drawn at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_show_glyph_string (cairo_t          *cr,
                               PangoFont        *font,
@@ -1066,12 +1066,12 @@ pango_cairo_show_glyph_string (cairo_t          *cr,
  * pango_cairo_show_glyph_item:
  * @cr: a Cairo context
  * @text: the UTF-8 text that @glyph_item refers to
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a `PangoGlyphItem`
  *
  * Draws the glyphs in @glyph_item in the specified cairo context,
  * embedding the text associated with the glyphs in the output if the
  * output format supports it (PDF for example), otherwise it acts
- * similar to pango_cairo_show_glyph_string().
+ * similar to [func@show_glyph_string].
  *
  * The origin of the glyphs (the left edge of the baseline) will
  * be drawn at the current point of the cairo context.
@@ -1080,7 +1080,7 @@ pango_cairo_show_glyph_string (cairo_t          *cr,
  * indexed by `glyph_item->item->offset`.
  *
  * Since: 1.22
- **/
+ */
 void
 pango_cairo_show_glyph_item (cairo_t          *cr,
                             const char       *text,
@@ -1096,14 +1096,14 @@ pango_cairo_show_glyph_item (cairo_t          *cr,
 /**
  * pango_cairo_show_layout_line:
  * @cr: a Cairo context
- * @line: a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  *
- * Draws a #PangoLayoutLine in the specified cairo context.
+ * Draws a `PangoLayoutLine` in the specified cairo context.
  * The origin of the glyphs (the left edge of the line) will
  * be drawn at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_show_layout_line (cairo_t          *cr,
                              PangoLayoutLine  *line)
@@ -1119,12 +1119,12 @@ pango_cairo_show_layout_line (cairo_t          *cr,
  * @cr: a Cairo context
  * @layout: a Pango layout
  *
- * Draws a #PangoLayout in the specified cairo context.
- * The top-left corner of the #PangoLayout will be drawn
+ * Draws a `PangoLayout` in the specified cairo context.
+ * The top-left corner of the `PangoLayout` will be drawn
  * at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_show_layout (cairo_t     *cr,
                         PangoLayout *layout)
@@ -1145,12 +1145,12 @@ pango_cairo_show_layout (cairo_t     *cr,
  *
  * Draw a squiggly line in the specified cairo context that approximately
  * covers the given rectangle in the style of an underline used to indicate a
- * spelling error.  (The width of the underline is rounded to an integer
+ * spelling error. (The width of the underline is rounded to an integer
  * number of up/down segments and the resulting rectangle is centered in the
  * original rectangle)
  *
  * Since: 1.14
- **/
+ */
 void
 pango_cairo_show_error_underline (cairo_t *cr,
                                  double  x,
@@ -1167,15 +1167,15 @@ pango_cairo_show_error_underline (cairo_t *cr,
 /**
  * pango_cairo_glyph_string_path:
  * @cr: a Cairo context
- * @font: a #PangoFont from a #PangoCairoFontMap
- * @glyphs: a #PangoGlyphString
+ * @font: a `PangoFont` from a `PangoCairoFontMap`
+ * @glyphs: a `PangoGlyphString`
  *
  * Adds the glyphs in @glyphs to the current path in the specified
  * cairo context. The origin of the glyphs (the left edge of the baseline)
  * will be at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_glyph_string_path (cairo_t          *cr,
                               PangoFont        *font,
@@ -1190,14 +1190,14 @@ pango_cairo_glyph_string_path (cairo_t          *cr,
 /**
  * pango_cairo_layout_line_path:
  * @cr: a Cairo context
- * @line: a #PangoLayoutLine
+ * @line: a `PangoLayoutLine`
  *
- * Adds the text in #PangoLayoutLine to the current path in the
- * specified cairo context.  The origin of the glyphs (the left edge
+ * Adds the text in `PangoLayoutLine` to the current path in the
+ * specified cairo context. The origin of the glyphs (the left edge
  * of the line) will be at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_layout_line_path (cairo_t          *cr,
                              PangoLayoutLine  *line)
@@ -1213,12 +1213,12 @@ pango_cairo_layout_line_path (cairo_t          *cr,
  * @cr: a Cairo context
  * @layout: a Pango layout
  *
- * Adds the text in a #PangoLayout to the current path in the
- * specified cairo context.  The top-left corner of the #PangoLayout
+ * Adds the text in a `PangoLayout` to the current path in the
+ * specified cairo context. The top-left corner of the `PangoLayout`
  * will be at the current point of the cairo context.
  *
  * Since: 1.10
- **/
+ */
 void
 pango_cairo_layout_path (cairo_t     *cr,
                         PangoLayout *layout)
@@ -1239,12 +1239,12 @@ pango_cairo_layout_path (cairo_t     *cr,
  *
  * Add a squiggly line to the current path in the specified cairo context that
  * approximately covers the given rectangle in the style of an underline used
- * to indicate a spelling error.  (The width of the underline is rounded to an
+ * to indicate a spelling error. (The width of the underline is rounded to an
  * integer number of up/down segments and the resulting rectangle is centered
  * in the original rectangle)
  *
  * Since: 1.14
- **/
+ */
 void
 pango_cairo_error_underline_path (cairo_t *cr,
                                  double   x,