[pango/gi-docs: 26/28] pangocairo: Tweak docs

[Matthias Clasen <matthiasc src gnome org>]

commit 7178d2b564c524cd492be60f22fa8e51920114c1
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Feb 22 00:25:44 2021 -0500

    pangocairo: Tweak docs
    
    Convert link syntax, and summaries.

 pango/pangocairo-context.c | 37 +++++++++++++++++++++++++------------
 pango/pangocairo-fontmap.c | 12 ++++++++----
 pango/pangocairo-render.c  | 28 +++++++++++++++++++++-------
 pango/pangocairo.h         | 16 ++++++++++------
 4 files changed, 64 insertions(+), 29 deletions(-)
---
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index b75c64d6..1d8e263f 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -162,8 +162,10 @@ _pango_cairo_update_context (cairo_t      *cr,
  *
  * 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
+ * context.
+ *
+ * If any layouts have been created for the context,
+ * it's necessary to call [method@Pango.Layout.context_changed] on those
  * layouts.
  *
  * Since: 1.10
@@ -185,7 +187,9 @@ pango_cairo_update_context (cairo_t      *cr,
  *   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
+ * Sets the resolution for the context.
+ *
+ * This is a scale factor between
  * 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).
@@ -230,6 +234,7 @@ pango_cairo_context_get_resolution (PangoContext *context)
  *   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 [func@update_context]
  * derives from the target surface.
  *
@@ -282,7 +287,9 @@ pango_cairo_context_set_font_options (PangoContext               *context,
  * @context: a `PangoContext`, from a pangocairo font map
  *
  * Retrieves any font rendering options previously set with
- * [method@PangoCairo.Context.set_font_options]. This function
+ * [method@PangoCairo.Context.set_font_options].
+ *
+ * This function
  * does not report options that are derived from the target
  * surface by [func@update_context].
  *
@@ -346,8 +353,9 @@ _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
- * details.
+ * of type %PANGO_ATTR_SHAPE.
+ *
+ * See `PangoCairoShapeRendererFunc` for details.
  *
  * Since: 1.18
  */
@@ -377,8 +385,9 @@ pango_cairo_context_set_shape_renderer (PangoContext                *context,
  * @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
- * details.
+ * 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
@@ -419,8 +428,10 @@ 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
- * used to create a layout using pango_layout_new().
+ * and target surface of the Cairo context.
+ *
+ * This context can then be
+ * used to create a layout using [ctor 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
@@ -452,9 +463,11 @@ 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
+ * [method@Pango.Layout.get_size] or drawing with functions like
  * [func@show_layout]. If you change the transformation or target
  * surface for @cr, you need to call [func@update_layout].
  *
diff --git a/pango/pangocairo-fontmap.c b/pango/pangocairo-fontmap.c
index 5f24ec93..5d5cc6f0 100644
--- a/pango/pangocairo-fontmap.c
+++ b/pango/pangocairo-fontmap.c
@@ -47,9 +47,10 @@ pango_cairo_font_map_default_init (PangoCairoFontMapIface *iface)
 /**
  * pango_cairo_font_map_new:
  *
- * Creates a new `PangoCairoFontMap` object; a fontmap is used
- * to cache information about available fonts, and holds
- * certain global parameters such as the resolution.
+ * 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 `func@font_map_get_default]
  * instead.
  *
@@ -225,7 +226,9 @@ pango_cairo_font_map_set_default (PangoCairoFontMap *fontmap)
  * @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
+ * Sets the resolution for the fontmap.
+ *
+ * This is a scale factor between
  * 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).
@@ -246,6 +249,7 @@ pango_cairo_font_map_set_resolution (PangoCairoFontMap *fontmap,
  * @fontmap: a `PangoCairoFontMap`
  *
  * Gets the resolution for the fontmap.
+ *
  * See [method@PangoCairo.FontMap.set_resolution].
  *
  * Return value: the resolution in "dots per inch"
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 47beb100..9e3cfab8 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -1045,6 +1045,7 @@ _pango_cairo_do_error_underline (cairo_t *cr,
  * @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.
  *
@@ -1069,6 +1070,7 @@ pango_cairo_show_glyph_string (cairo_t          *cr,
  * @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 [func@show_glyph_string].
@@ -1099,6 +1101,7 @@ pango_cairo_show_glyph_item (cairo_t          *cr,
  * @line: a `PangoLayoutLine`
  *
  * 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.
  *
@@ -1120,6 +1123,7 @@ pango_cairo_show_layout_line (cairo_t          *cr,
  * @layout: a Pango layout
  *
  * 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.
  *
@@ -1145,9 +1149,11 @@ 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)
+ * original rectangle.
  *
  * Since: 1.14
  */
@@ -1171,7 +1177,9 @@ pango_cairo_show_error_underline (cairo_t *cr,
  * @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)
+ * 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
@@ -1193,7 +1201,9 @@ pango_cairo_glyph_string_path (cairo_t          *cr,
  * @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
+ * 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
@@ -1214,7 +1224,9 @@ pango_cairo_layout_line_path (cairo_t          *cr,
  * @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`
+ * specified cairo context.
+ *
+ * The top-left corner of the `PangoLayout`
  * will be at the current point of the cairo context.
  *
  * Since: 1.10
@@ -1239,9 +1251,11 @@ 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)
+ * in the original rectangle.
  *
  * Since: 1.14
  */
diff --git a/pango/pangocairo.h b/pango/pangocairo.h
index 633ccf9d..7e860554 100644
--- a/pango/pangocairo.h
+++ b/pango/pangocairo.h
@@ -30,9 +30,11 @@ G_BEGIN_DECLS
 /**
  * PangoCairoFont:
  *
- * #PangoCairoFont is an interface exported by fonts for
- * use with Cairo. The actual type of the font will depend
- * on the particular font technology Cairo was compiled to use.
+ * `PangoCairoFont` is an interface exported by fonts for
+ * use with Cairo.
+ *
+ * The actual type of the font will depend on the particular
+ * font technology Cairo was compiled to use.
  *
  * Since: 1.18
  **/
@@ -55,9 +57,11 @@ typedef struct _PangoCairoFont      PangoCairoFont;
 /**
  * PangoCairoFontMap:
  *
- * #PangoCairoFontMap is an interface exported by font maps for
- * use with Cairo. The actual type of the font map will depend
- * on the particular font technology Cairo was compiled to use.
+ * `PangoCairoFontMap` is an interface exported by font maps for
+ * use with Cairo.
+ *
+ * The actual type of the font map will depend on the particular
+ * font technology Cairo was compiled to use.
  *
  * Since: 1.10
  **/