diff options
author | Matthias Clasen <mclasen@redhat.com> | 2021-02-19 08:12:08 -0500 |
---|---|---|
committer | Matthias Clasen <mclasen@redhat.com> | 2021-03-11 13:17:36 -0500 |
commit | b06600416513594f07989479e81403eb4c90fd36 (patch) | |
tree | 252111ef460cea79c34072b56ec1da7eb7bc340d | |
parent | 2347ac3c58ac694172b6888f79c97d1a9d42bb97 (diff) | |
download | pango-b06600416513594f07989479e81403eb4c90fd36.tar.gz |
docs: Tweak gravity docs
Add summaries, convert markup, etc.
-rw-r--r-- | pango/pango-gravity.c | 28 | ||||
-rw-r--r-- | 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 **/ |