[pango/gi-docs: 17/28] docs: Tweak gravity docs

[Matthias Clasen <matthiasc src gnome org>]

commit f419dd335808661e8966d7eec4e120c76c5e51a2
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 19 08:12:08 2021 -0500

    docs: Tweak gravity docs
    
    Add summaries, convert markup, etc.

 pango/pango-gravity.c | 28 +++++++++++++++-------------
 pango/pango-gravity.h | 30 +++++++++++++++++-------------
 2 files changed, 32 insertions(+), 26 deletions(-)
---
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index ea6ef9e2..f1c3f185 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -27,13 +27,12 @@
 
 /**
  * pango_gravity_to_rotation:
- * @gravity: gravity to query
+ * @gravity: gravity to query, should not be %PANGO_GRAVITY_AUTO
  *
  * Converts a #PangoGravity value to its natural rotation in radians.
- * @gravity should not be %PANGO_GRAVITY_AUTO.
  *
- * Note that pango_matrix_rotate() takes angle in degrees, not radians.
- * So, to call pango_matrix_rotate() with the output of this function
+ * Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians.
+ * So, to call [method@Pango.Matrix,rotate] with the output of this function
  * you should multiply it by (180. / G_PI).
  *
  * Return value: the rotation value corresponding to @gravity.
@@ -62,10 +61,10 @@ pango_gravity_to_rotation (PangoGravity gravity)
 
 /**
  * pango_gravity_get_for_matrix:
- * @matrix: (nullable): a #PangoMatrix
+ * @matrix: (nullable): a `PangoMatrix`
  *
  * Finds the gravity that best matches the rotation component
- * in a #PangoMatrix.
+ * in a `PangoMatrix`.
  *
  * Return value: the gravity of @matrix, which will never be
  * %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL
@@ -237,8 +236,9 @@ get_script_properties (PangoScript script)
  * @base_gravity: base gravity of the paragraph
  * @hint: orientation hint
  *
- * Based on the script, base gravity, and hint, returns actual gravity
- * to use in laying out a single #PangoItem.
+ * Returns the gravity to use in laying out a `PangoItem`.
+ *
+ * The gravity is determined based on the script, base gravity, and hint.
  *
  * If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the
  * preferred gravity of @script.  To get the preferred gravity of a script,
@@ -270,13 +270,15 @@ pango_gravity_get_for_script (PangoScript      script,
  * @base_gravity: base gravity of the paragraph
  * @hint: orientation hint
  *
- * Based on the script, East Asian width, base gravity, and hint,
- * returns actual gravity to use in laying out a single character
- * or #PangoItem.
+ * Returns the gravity to use in laying out a single character
+ * or `PangoItem`.
+ *
+ * The gravity is determined based on the script, East Asian width,
+ * base gravity, and hint,
  *
- * This function is similar to pango_gravity_get_for_script() except
+ * This function is similar to [func@gravity_get_for_script] except
  * that this function makes a distinction between narrow/half-width and
- * wide/full-width characters also.  Wide/full-width characters always
+ * wide/full-width characters also. Wide/full-width characters always
  * stand *upright*, that is, they always take the base gravity,
  * whereas narrow/full-width characters are always rotated in vertical
  * context.
diff --git a/pango/pango-gravity.h b/pango/pango-gravity.h
index 63c29e5e..a3aa7f19 100644
--- a/pango/pango-gravity.h
+++ b/pango/pango-gravity.h
@@ -34,19 +34,22 @@ G_BEGIN_DECLS
  * @PANGO_GRAVITY_WEST: Glyphs are rotated 90 degrees counter-clockwise
  * @PANGO_GRAVITY_AUTO: Gravity is resolved from the context matrix
  *
- * The #PangoGravity type represents the orientation of glyphs in a segment
- * of text.  This is useful when rendering vertical text layouts.  In
- * those situations, the layout is rotated using a non-identity PangoMatrix,
- * and then glyph orientation is controlled using #PangoGravity.
+ * `PangoGravity` represents the orientation of glyphs in a segment
+ * of text.
+ *
+ * This is useful when rendering vertical text layouts. In those situations,
+ * the layout is rotated using a non-identity [struct@Pango.Matrix], and then
+ * glyph orientation is controlled using `PangoGravity`.
+ *
  * Not every value in this enumeration makes sense for every usage of
- * #PangoGravity; for example, %PANGO_GRAVITY_AUTO only can be passed to
- * pango_context_set_base_gravity() and can only be returned by
- * pango_context_get_base_gravity().
+ * `PangoGravity`; for example, %PANGO_GRAVITY_AUTO only can be passed to
+ * [method@Pango.Context.set_base_gravity] and can only be returned by
+ * [method@Pango.Context.get_base_gravity].
  *
- * See also: #PangoGravityHint
+ * See also: [enum@Pango.GravityHint]
  *
  * Since: 1.16
- **/
+ */
 typedef enum {
   PANGO_GRAVITY_SOUTH,
   PANGO_GRAVITY_EAST,
@@ -66,11 +69,12 @@ typedef enum {
  * respects the line progression.  This means, Latin and Arabic will take
  * opposite gravities and both flow top-to-bottom for example.
  *
- * The #PangoGravityHint defines how horizontal scripts should behave in a
- * vertical context.  That is, English excerpt in a vertical paragraph for
- * example.
+ * `PangoGravityHint` defines how horizontal scripts should behave in a
+ * vertical context.
+ *
+ * That is, English excerpts in a vertical paragraph for example.
  *
- * See #PangoGravity.
+ * See also [enum@Pango.Gravity]
  *
  * Since: 1.16
  **/