[pango/gi-docs: 34/45] docs: Tweak layout docs

[Matthias Clasen <matthiasc src gnome org>]

commit 1d1372ac0b3132eb5b743e9ec28f07214c5c1d44
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Feb 19 08:10:54 2021 -0500

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

 pango/pango-layout.c | 220 +++++++++++++++++++++++++++++----------------------
 pango/pango-layout.h |  31 ++++----
 2 files changed, 141 insertions(+), 110 deletions(-)
---
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index d287df50..2a836f64 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -20,25 +20,24 @@
  */
 
 /**
- * SECTION:pangolayout
- * @short_description:High-level layout driver objects
- * @title:Layout Objects
+ * PangoLayout:
+ *
+ * A `PangoLayout` structure represents an entire paragraph of text.
  *
  * While complete access to the layout capabilities of Pango is provided
  * using the detailed interfaces for itemization and shaping, using
  * that functionality directly involves writing a fairly large amount
- * of code. The objects and functions in this section provide a
- * high-level driver for formatting entire paragraphs of text
- * at once. This includes paragraph-level functionality such as
- * line breaking, justification, alignment and ellipsization.
- *
- * The `PangoLayout` structure represents an entire paragraph
- * of text. It is initialized with a `PangoContext`, UTF-8 string
- * and set of attributes for that string. Once that is done, the
- * set of formatted lines can be extracted from the object,
- * the layout can be rendered, and conversion between logical
- * character positions within the layout's text, and the physical
- * position of the resulting glyphs can be made.
+ * of code. `PangoLayout` provides a high-level driver for formatting
+ * entire paragraphs of text at once. This includes paragraph-level
+ * functionality such as line breaking, justification, alignment and
+ * ellipsization.
+ *
+ * A `PangoLayout is initialized with a `PangoContext`, UTF-8 string
+ * and set of attributes for that string. Once that is done, the set of
+ * formatted lines can be extracted from the object, the layout can be
+ * rendered, and conversion between logical character positions within
+ * the layout's text, and the physical position of the resulting glyphs
+ * can be made.
  *
  * There are a number of parameters to adjust the formatting of a
  * `PangoLayout`. The following image shows adjustable parameters
@@ -50,18 +49,13 @@
  * and simply treat the results of a `PangoLayout` as a list of lines.
  */
 
-/**
- * PangoLayout:
- *
- * The `PangoLayout` structure is opaque, and has no user-visible fields.
- */
-
 /**
  * PangoLayoutIter:
  *
- * A `PangoLayoutIter` structure can be used to iterate over the visual
- * extents of a [class@Pango.Layout]. To obtain a `PangoLayoutIter`, use
- * pango_layout_get_iter().
+ * A `PangoLayoutIter` can be used to iterate over the visual
+ * extents of a `PangoLayout`.
+ *
+ * To obtain a `PangoLayoutIter`, use [method@Pango.Layout.get_iter].
  *
  * The `PangoLayoutIter` structure is opaque, and has no user-visible fields.
  */
@@ -285,9 +279,10 @@ pango_layout_new (PangoContext *context)
  * pango_layout_copy:
  * @src: a `PangoLayout`
  *
- * Does a deep copy-by-value of the @src layout. The attribute list,
- * tab array, and text from the original layout are all copied by
- * value.
+ * Creates a deep copy-by-value of the layout.
+ *
+ * The attribute list, tab array, and text from the original layout
+ * are all copied by value.
  *
  * Return value: (transfer full): the newly allocated `PangoLayout`,
  *   with a reference count of one, which should be freed
@@ -345,7 +340,9 @@ pango_layout_get_context (PangoLayout *layout)
  *   wrapping or ellipsization should be performed.
  *
  * Sets the width to which the lines of the `PangoLayout` should wrap or
- * ellipsized. The default value is -1: no width set.
+ * ellipsized.
+ *
+ * The default value is -1: no width set.
  */
 void
 pango_layout_set_width (PangoLayout *layout,
@@ -390,6 +387,7 @@ pango_layout_get_width (PangoLayout    *layout)
  *   or desired number of lines if negative.
  *
  * Sets the height to which the `PangoLayout` should be ellipsized at.
+ *
  * There are two different behaviors, based on whether @height is positive
  * or negative.
  *
@@ -442,6 +440,7 @@ pango_layout_set_height (PangoLayout *layout,
  * @layout: a `PangoLayout`
  *
  * Gets the height of layout used for ellipsization.
+ *
  * See [method@Pango.Layout.set_height] for details.
  *
  * Return value: the height, in Pango units if positive,
@@ -461,9 +460,11 @@ pango_layout_get_height (PangoLayout *layout)
  * @layout: a `PangoLayout`
  * @wrap: the wrap mode
  *
- * Sets the wrap mode; the wrap mode only has effect if a width
- * is set on the layout with [method@Pango.Layout.set_width].
- * To turn off wrapping, set the width to -1.
+ * Sets the wrap mode.
+ *
+ * The wrap mode only has effect if a width is set on the layout
+ * with [method@Pango.Layout.set_width]. To turn off wrapping,
+ * set the width to -1.
  */
 void
 pango_layout_set_wrap (PangoLayout   *layout,
@@ -556,8 +557,9 @@ pango_layout_set_indent (PangoLayout *layout,
  * pango_layout_get_indent:
  * @layout: a `PangoLayout`
  *
- * Gets the paragraph indent width in Pango units. A negative value
- * indicates a hanging indentation.
+ * Gets the paragraph indent width in Pango units.
+ *
+ * A negative value indicates a hanging indentation.
  *
  * Return value: the indent in Pango units.
  */
@@ -574,8 +576,9 @@ pango_layout_get_indent (PangoLayout *layout)
  * @spacing: the amount of spacing
  *
  * Sets the amount of spacing in Pango unit between
- * the lines of the layout. When placing lines with
- * spacing, Pango arranges things so that
+ * the lines of the layout.
+ *
+ * When placing lines with spacing, Pango arranges things so that
  *
  * line2.top = line1.bottom + spacing
  *
@@ -619,8 +622,8 @@ pango_layout_get_spacing (PangoLayout *layout)
  * @factor: the new line spacing factor
  *
  * Sets a factor for line spacing.
- * Typical values are: 0, 1, 1.5, 2.
- * The default values is 0.
+ *
+ * Typical values are: 0, 1, 1.5, 2. The default values is 0.
  *
  * If @factor is non-zero, lines are placed so that
  *
@@ -651,8 +654,9 @@ pango_layout_set_line_spacing (PangoLayout *layout,
  * pango_layout_get_line_spacing:
  * @layout: a `PangoLayout`
  *
- * Gets the value that has been set with
- * [method@Pango.Layout.set_line_spacing].
+ * Gets the line spacing factor of @layout.
+ *
+ * See [method@Pango.Layout.set_line_spacing].
  *
  * Since: 1.44
  */
@@ -726,8 +730,9 @@ pango_layout_get_attributes (PangoLayout *layout)
  * @desc: (allow-none): the new `PangoFontDescription`, or %NULL
  *   to unset the current font description
  *
- * Sets the default font description for the layout. If no font
- * description is set on the layout, the font description from
+ * Sets the default font description for the layout.
+ *
+ * If no font description is set on the layout, the font description from
  * the layout's context is used.
  */
 void
@@ -776,10 +781,11 @@ pango_layout_get_font_description (PangoLayout *layout)
  * @justify: whether the lines in the layout should be justified.
  *
  * Sets whether each complete line should be stretched to fill the
- * entire width of the layout. This stretching is typically done by
- * adding whitespace, but for some scripts (such as Arabic), the
- * justification may be done in more complex ways, like extending
- * the characters.
+ * entire width of the layout.
+ *
+ * Stretching is typically done by adding whitespace, but for some scripts
+ * (such as Arabic), the justification may be done in more complex ways,
+ * like extending the characters.
  *
  * Note that this setting is not implemented and so is ignored in
  * Pango older than 1.18.
@@ -821,14 +827,14 @@ pango_layout_get_justify (PangoLayout *layout)
  * @auto_dir: if %TRUE, compute the bidirectional base direction
  *   from the layout's contents.
  *
- * Sets whether to calculate the bidirectional base direction
- * for the layout according to the contents of the layout;
- * when this flag is on (the default), then paragraphs in
-   @layout that begin with strong right-to-left characters
- * (Arabic and Hebrew principally), will have right-to-left
- * layout, paragraphs with letters from other scripts will
- * have left-to-right layout. Paragraphs with only neutral
- * characters get their direction from the surrounding paragraphs.
+ * Sets whether to calculate the base direction
+ * for the layout according to its contents.
+ *
+ * When this flag is on (the default), then paragraphs in @layout that
+ * begin with strong right-to-left characters (Arabic and Hebrew principally),
+ * will have right-to-left layout, paragraphs with letters from other scripts
+ * will have left-to-right layout. Paragraphs with only neutral characters
+ * get their direction from the surrounding paragraphs.
  *
  * When %FALSE, the choice between left-to-right and right-to-left
  * layout is done according to the base direction of the layout's
@@ -859,8 +865,9 @@ pango_layout_set_auto_dir (PangoLayout *layout,
  * pango_layout_get_auto_dir:
  * @layout: a `PangoLayout`
  *
- * Gets whether to calculate the bidirectional base direction
- * for the layout according to the contents of the layout.
+ * Gets whether to calculate the base direction for the layout
+ * according to its contents.
+ *
  * See [method@Pango.Layout.set_auto_dir].
  *
  * Return value: %TRUE if the bidirectional base direction
@@ -919,8 +926,9 @@ pango_layout_get_alignment (PangoLayout *layout)
  * @layout: a `PangoLayout`
  * @tabs: (allow-none): a `PangoTabArray`, or %NULL
  *
- * Sets the tabs to use for @layout, overriding the default tabs
- * (by default, tabs are every 8 spaces). If @tabs is %NULL, the
+ * Sets the tabs to use for @layout, overriding the default tabs.
+ *
+ * By default, tabs are every 8 spaces. If @tabs is %NULL, the
  * default tabs are reinstated. @tabs is copied into the layout;
  * you must free your copy of @tabs yourself.
  */
@@ -972,6 +980,8 @@ pango_layout_get_tabs (PangoLayout *layout)
  * @layout: a `PangoLayout`
  * @setting: new setting
  *
+ * Sets the single paragraph mode of @layout.
+ *
  * If @setting is %TRUE, do not treat newlines and similar characters
  * as paragraph separators; instead, keep all text in a single paragraph,
  * and display a glyph for paragraph separator characters. Used when
@@ -996,7 +1006,9 @@ pango_layout_set_single_paragraph_mode (PangoLayout *layout,
  * pango_layout_get_single_paragraph_mode:
  * @layout: a `PangoLayout`
  *
- * Obtains the value set by [method@Pango.Layout.set_single_paragraph_mode].
+ * Obtains whether @layout is in single paragraph mode.
+ *
+ * See [method@Pango.Layout.set_single_paragraph_mode].
  *
  * Return value: %TRUE if the layout does not break paragraphs at
  * paragraph separator characters, %FALSE otherwise.
@@ -1015,6 +1027,7 @@ pango_layout_get_single_paragraph_mode (PangoLayout *layout)
  * @ellipsize: the new ellipsization mode for @layout
  *
  * Sets the type of ellipsization being performed for @layout.
+ *
  * Depending on the ellipsization mode @ellipsize text is
  * removed from the start, middle, or end of text so they
  * fit within the width and height of layout set with
@@ -1048,6 +1061,7 @@ pango_layout_set_ellipsize (PangoLayout        *layout,
  * @layout: a `PangoLayout`
  *
  * Gets the type of ellipsization being performed for @layout.
+ *
  * See [method@Pango.Layout.set_ellipsize].
  *
  * Use [method@Pango.Layout.is_ellipsized] to query whether any
@@ -1223,7 +1237,12 @@ pango_layout_get_character_count (PangoLayout *layout)
  * @length: length of marked-up text in bytes, or -1 if @markup is
  *   null-terminated
  *
- * Same as [method@Pango.Layout.set_markup_with_accel],
+ * Sets the layout text and attribute list from marked-up text.
+ *
+ * See [Pango Markup](pango_markup.html)).
+ * Replaces the current text and attribute list.
+ *
+ * This is the Same as [method@Pango.Layout.set_markup_with_accel],
  * but the markup text isn't scanned for accelerators.
  */
 void
@@ -1244,9 +1263,10 @@ pango_layout_set_markup (PangoLayout *layout,
  * @accel_char: (out caller-allocates) (allow-none): return location
  *   for first located accelerator, or %NULL
  *
- * Sets the layout text and attribute list from marked-up text (see
- * [Pango Markup](pango_markup.html)). Replaces the current text
- * and attribute list.
+ * Sets the layout text and attribute list from marked-up text.
+ *
+ * See [Pango Markup](pango_markup.html)).
+ * Replaces the current text and attribute list.
  *
  * If @accel_marker is nonzero, the given character will mark the
  * character following it as an accelerator. For example, @accel_marker
@@ -1292,9 +1312,7 @@ pango_layout_set_markup_with_accel (PangoLayout *layout,
  * pango_layout_get_unknown_glyphs_count:
  * @layout: a `PangoLayout`
  *
- * Counts the number unknown glyphs in @layout. That is, zero if
- * glyphs for all characters in the layout text were found, or more
- * than zero otherwise.
+ * Counts the number of unknown glyphs in @layout.
  *
  * This function can be used to determine if there are any fonts
  * available to render all characters in a certain string, or when
@@ -1371,9 +1389,10 @@ layout_changed (PangoLayout *layout)
  * @layout: a `PangoLayout`
  *
  * Forces recomputation of any state in the `PangoLayout` that
- * might depend on the layout's context. This function should
- * be called if you make changes to the context subsequent
- * to creating the layout.
+ * might depend on the layout's context.
+ *
+ * This function should be called if you make changes to the context
+ * subsequent to creating the layout.
  */
 void
 pango_layout_context_changed (PangoLayout *layout)
@@ -1388,12 +1407,13 @@ pango_layout_context_changed (PangoLayout *layout)
  * pango_layout_get_serial:
  * @layout: a `PangoLayout`
  *
- * Returns the current serial number of @layout. The serial number is
- * initialized to an small number larger than zero when a new layout
- * is created and is increased whenever the layout is changed using any
- * of the setter functions, or the `PangoContext` it uses has changed.
- * The serial may wrap, but will never have the value 0. Since it
- * can wrap, never compare it with "less than", always use "not equals".
+ * Returns the current serial number of @layout.
+ *
+ * The serial number is initialized to an small number larger than zero
+ * when a new layout is created and is increased whenever the layout is
+ * changed using any of the setter functions, or the `PangoContext` it
+ * uses has changed. The serial may wrap, but will never have the value 0.
+ * Since it can wrap, never compare it with "less than", always use "not equals".
  *
  * This can be used to automatically detect changes to a `PangoLayout`,
  * and is useful for example to decide whether a layout needs redrawing.
@@ -1804,7 +1824,8 @@ pango_layout_index_to_line_and_extents (PangoLayout     *layout,
  *   (%PANGO_SCALE units per device unit), or %NULL
  *
  * Converts from byte @index_ within the @layout to line and X position.
- * (X position is measured from the left edge of the line)
+ *
+ * The X position is measured from the left edge of the line.
  */
 void
 pango_layout_index_to_line_x (PangoLayout *layout,
@@ -1869,10 +1890,12 @@ pango_layout_index_to_line_x (PangoLayout *layout,
  *   the cursor should be displayed.
  *
  * Computes a new cursor position from an old position and a count of
- * positions to move visually. If @direction is positive, then the new
- * strong cursor position will be one position to the right of the old
- * cursor position. If @direction is negative, then the new strong cursor
- * position will be one position to the left of the old cursor position.
+ * positions to move visually.
+ *
+ * If @direction is positive, then the new strong cursor position will be
+ * one position to the right of the old cursor position. If @direction is
+ * negative, then the new strong cursor position will be one position to
+ * the left of the old cursor position.
  *
  * In the presence of bidirectional text, the correspondence between
  * logical and visual order will depend on the direction of the current
@@ -2042,7 +2065,9 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
  *   of the grapheme.
  *
  * Converts from X and Y position within a layout to the byte index to the
- * character at that logical position. If the Y position is not inside the
+ * character at that logical position.
+ *
+ * If the Y position is not inside the
  * layout, the closest position is chosen (the position will be clamped
  * inside the layout). If the X position is not within the layout, then
  * the start or the end of the line is chosen as described for
@@ -2142,11 +2167,12 @@ pango_layout_xy_to_index (PangoLayout *layout,
  * @pos: (out): rectangle in which to store the position of the grapheme
  *
  * Converts from an index within a `PangoLayout` to the onscreen position
- * corresponding to the grapheme at that index, which is represented
- * as rectangle. Note that `pos->x` is always the leading edge of the
- * grapheme and `pos->x + pos->width` the trailing edge of the grapheme.
- * If the directionality of the grapheme is right-to-left, then `pos->width`
- * will be negative.
+ * corresponding to the grapheme at that index.
+ *
+ * The return value is represented as rectangle. Note that `pos->x` is
+ * always the leading edge of the grapheme and `pos->x + pos->width` the
+ * trailing edge of the grapheme. If the directionality of the grapheme
+ * is right-to-left, then `pos->width` will be negative.
  */
 void
 pango_layout_index_to_pos (PangoLayout    *layout,
@@ -2401,12 +2427,13 @@ pango_layout_get_direction (PangoLayout *layout,
  *   position (may be %NULL)
  *
  * Given an index within a layout, determines the positions that of the
- * strong and weak cursors if the insertion point is at that index. The
- * position of each cursor is stored as a zero-width rectangle. The strong
- * cursor location is the location where characters of the directionality
- * equal to the base direction of the layout are inserted. The weak cursor
- * location is the location where characters of the directionality opposite
- * to the base direction of the layout are inserted.
+ * strong and weak cursors if the insertion point is at that index.
+ *
+ * The position of each cursor is stored as a zero-width rectangle.
+ * The strong cursor location is the location where characters of the
+ * directionality equal to the base direction of the layout are inserted.
+ * The weak cursor location is the location where characters of the
+ * directionality opposite to the base direction of the layout are inserted.
  */
 void
 pango_layout_get_cursor_pos (PangoLayout    *layout,
@@ -2896,8 +2923,9 @@ pango_layout_get_pixel_extents (PangoLayout    *layout,
  * @height: (out) (allow-none): location to store the logical height, or %NULL
  *
  * Determines the logical width and height of a `PangoLayout` in Pango
- * units (device units scaled by %PANGO_SCALE). This is simply a
- * convenience function around [method@Pango.Layout.get_extents].
+ * units.
+ *
+ * This is simply a convenience function around [method@Pango.Layout.get_extents].
  */
 void
 pango_layout_get_size (PangoLayout *layout,
@@ -2921,8 +2949,10 @@ pango_layout_get_size (PangoLayout *layout,
  * @height: (out) (allow-none): location to store the logical height, or %NULL
  *
  * Determines the logical width and height of a `PangoLayout` in device
- * units. ([method@Pango.Layout.get_size] returns the width and height
- * scaled by %PANGO_SCALE.) This is simply a convenience function around
+ * units.
+ *
+ * [method@Pango.Layout.get_size] returns the width and height
+ * scaled by %PANGO_SCALE. This is simply a convenience function around
  * [method@Pango.Layout.get_pixel_extents].
  */
 void
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 6182d889..4a464230 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -36,10 +36,9 @@ typedef struct _PangoLayoutLine  PangoLayoutLine;
 /**
  * PangoLayoutRun:
  *
- * The `PangoLayoutRun` structure represents a single run within
- * a [struct@Pango.LayoutLine]; it is simply an alternate name for
- * [struct@Pango.GlyphItem].
+ * A `PangoLayoutRun` represents a single run within a `PangoLayoutLine`.
  *
+ * It is simply an alternate name for [struct@Pango.GlyphItem].
  * See the [struct@Pango.GlyphItem] docs for details on the fields.
  */
 typedef PangoGlyphItem PangoLayoutRun;
@@ -50,10 +49,11 @@ typedef PangoGlyphItem PangoLayoutRun;
  * @PANGO_ALIGN_CENTER: Center the line within the available space
  * @PANGO_ALIGN_RIGHT: Put all available space on the left
  *
- * A `PangoAlignment` describes how to align the lines of a `PangoLayout`
- * within the available space. If the `PangoLayout` is set to justify
- * using [method@Pango.Layout.set_justify], this only has effect for
- * partial lines.
+ * `PangoAlignment` describes how to align the lines of a `PangoLayout`
+ * within the available space.
+ *
+ * If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify],
+ * this only has effect for partial lines.
  */
 typedef enum {
   PANGO_ALIGN_LEFT,
@@ -68,7 +68,7 @@ typedef enum {
  * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to
  *   character boundaries if there is not enough space for a full word.
  *
- * A `PangoWrapMode` describes how to wrap the lines of a `PangoLayout`
+ * `PangoWrapMode` describes how to wrap the lines of a `PangoLayout`
  * to the desired width.
  */
 typedef enum {
@@ -84,8 +84,8 @@ typedef enum {
  * @PANGO_ELLIPSIZE_MIDDLE: Omit characters in the middle of the text
  * @PANGO_ELLIPSIZE_END: Omit characters at the end of the text
  *
- * The `PangoEllipsizeMode` type describes what sort of (if any)
- * ellipsization should be applied to a line of text.
+ * `PangoEllipsizeMode` describes what sort of ellipsization
+ * should be applied to text.
  *
  * In the ellipsization process characters are removed from the
  * text in order to make it fit to a given width and replaced
@@ -108,11 +108,12 @@ typedef enum {
  * @is_paragraph_start: #TRUE if this is the first line of the paragraph
  * @resolved_dir: #Resolved PangoDirection of line
  *
- * The `PangoLayoutLine` structure represents one of the lines resulting
- * from laying out a paragraph via [class@Pango.Layout]. `PangoLayoutLine`
- * structures are obtained by calling [method@Pango.Layout.get_line] and
- * are only valid until the text, attributes, or settings of the parent
- * `PangoLayout` are modified.
+ * A `PangoLayoutLine` represents one of the lines resulting from laying
+ * out a paragraph via `PangoLayout`.
+ *
+ * `PangoLayoutLine` structures are obtained by calling
+ * [method@Pango.Layout.get_line] and are only valid until the text,
+ * attributes, or settings of the parent `PangoLayout` are modified.
  */
 struct _PangoLayoutLine
 {