[pango/line-breaker] layout: Add docs

[Matthias Clasen <matthiasc src gnome org>]

commit c242bb9453c7c3ef580e6e3cde256dc0cacf6a35
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Jan 24 14:44:05 2022 -0500

    layout: Add docs

 pango/pango-layout.c | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
---
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 0e8945fc..7b952614 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -7,6 +7,55 @@
 #include "pango-markup.h"
 #include "pango-context.h"
 
+/**
+ * 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, segmentation and shaping,
+ * using that functionality directly involves writing a fairly large amount
+ * 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`, a UTF-8 string
+ * and set of attributes for that string. Once that is done, the set of
+ * formatted lines can be extracted in the form of a [class@Pango.Lines]
+ * 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.
+ *
+ * The most convenient way to access the visual extents and components
+ * of a formatted layout is via a [class@Pango.LayoutIter] iterator.
+ *
+ * There are a number of parameters to adjust the formatting of a
+ * `PangoLayout`. The following image shows adjustable parameters
+ * (on the left) and font metrics (on the right):
+ *
+ * <picture>
+ *   <source srcset="layout-dark.png" media="(prefers-color-scheme: dark)">
+ *   <img alt="Pango Layout Parameters" src="layout-light.png">
+ * </picture>
+ *
+ * The following images demonstrate the effect of alignment and justification
+ * on the layout of text:
+ *
+ * | | |
+ * | --- | --- |
+ * | ![align=left](align-left.png) | ![align=left, justify](align-left-justify.png) |
+ * | ![align=center](align-center.png) | ![align=center, justify](align-center-justify.png) |
+ * | ![align=right](align-right.png) | ![align=right, justify](align-right-justify.png) |
+ *
+ * It is possible, as well, to ignore the 2-D setup, and simply treat the
+ * resulting `PangoLines` object as a list of lines.
+ *
+ * If you have more complex line breaking needs, such as shaping text
+ * to flow around images, or multi-column layout, the [class@Pango.LineBreaker]
+ * makes the underlying line-breaking functionality available outside of
+ * `PangoLayout`.
+ */
+
 
 /* {{{ PangoLayout implementation */