summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMatthias Clasen <mclasen@redhat.com>2021-02-19 08:12:08 -0500
committerMatthias Clasen <mclasen@redhat.com>2021-03-11 13:17:36 -0500
commitb06600416513594f07989479e81403eb4c90fd36 (patch)
tree252111ef460cea79c34072b56ec1da7eb7bc340d
parent2347ac3c58ac694172b6888f79c97d1a9d42bb97 (diff)
downloadpango-b06600416513594f07989479e81403eb4c90fd36.tar.gz
docs: Tweak gravity docs
Add summaries, convert markup, etc.
-rw-r--r--pango/pango-gravity.c28
-rw-r--r--pango/pango-gravity.h30
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
**/