docs: Tweak gravity docs

Add summaries, convert markup, etc.

1 files changed, 17 insertions, 13 deletions

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
  **/