[pango/line-breaker] line-breaker: Add docs

[Matthias Clasen <matthiasc src gnome org>]

commit 054e7b27dbb122ff75200647900556cda11bc7b7
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Jan 24 14:49:53 2022 -0500

    line-breaker: Add docs

 pango/pango-line-breaker.c | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)
---
diff --git a/pango/pango-line-breaker.c b/pango/pango-line-breaker.c
index 175984f2..3c99b15e 100644
--- a/pango/pango-line-breaker.c
+++ b/pango/pango-line-breaker.c
@@ -28,11 +28,22 @@
  * to influence the formatting.
  *
  * Then you can call [method@Pango.LineBreaker.next_line] repeatedly to obtain
- * `PangoLayoutLine` objects for the text, one by one.
+ * `PangoLayoutLine` objects for the text, one by one. The parameters that are
+ * passed to `pango_line_breaker_next_line`, as well as properties of the
+ * `PangoLineBreaker` can be changed from call to call. For example, you can
+ * pass `PANGO_ELLIPSIZE_END` to consume the remaining text with a single,
+ * ellipsized line once you have produced enough lines to fill your desired
+ * height.
  *
- * `PangoLineBreaker` is meant to enable use cases like flowing text around images,
- * or shaped paragraphs. For simple formatting needs, [class@Pango.Layout]
- * is probably more convenient to use.
+ * A convenient way to keep track of the lines that are produced by `PangoLineBreaker`
+ * is to add them to a [class@Pango.Lines] object, together with positioning
+ * information. Before doing so, you can tweak the line or its offset, for
+ * example to implement alignment and justification (for the latter, see
+ * [method Pango Line.justify]).
+ *
+ * `PangoLineBreaker` is meant to enable use cases like flowing text around
+ * images, shaped paragraphs or multi-column layout. For simple formatting
+ * needs, [class@Pango.Layout] is probably more convenient to use.
  */
 
 typedef struct _LastTabState LastTabState;