Merge branch 'matthiasc/for-main' into 'main'

docs: Some clarifications

See merge request GNOME/pango!392

3 files changed, 12 insertions, 4 deletions

diff --git a/pango/fonts.c b/pango/fonts.c
index cd30811c..45d05b38 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -2115,8 +2115,8 @@ pango_font_metrics_get_descent (PangoFontMetrics *metrics)
  *
  * Gets the line height from a font metrics structure.
  *
- * The line height is the distance between successive baselines
- * in wrapped text.
+ * The line height is the recommended distance between successive
+ * baselines in wrapped text using this font.
  *
  * If the line height is not available, 0 is returned.
  *
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index ae0bc330..b39ca62b 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -5286,8 +5286,13 @@ pango_layout_line_get_extents (PangoLayoutLine *line,
  * @line: a `PangoLayoutLine`
  * @height: (out) (optional): return location for the line height
  *
- * Computes the height of the line, i.e. the distance between
- * this and the previous lines baseline.
+ * Computes the height of the line, as the maximum of the heights
+ * of fonts used in this line.
+ *
+ * Note that the actual baseline-to-baseline distance between lines
+ * of text is influenced by other factors, such as
+ * [method@Pango.Layout.set_spacing] and
+ * [method@Pango.Layout.set_line_spacing].
  *
  * Since: 1.44
  */
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 34758ae3..ab4029db 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -54,6 +54,9 @@ typedef PangoGlyphItem PangoLayoutRun;
  *
  * If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify],
  * this only has effect for partial lines.
+ *
+ * See [method@Pango.Layout.set_auto_dir] for how text direction affects
+ * the interpretation of `PangoAlignment values.
  */
 typedef enum {
   PANGO_ALIGN_LEFT,