From 3a012cc469d22b9889907a79717524e983ac95b7 Mon Sep 17 00:00:00 2001
From: Khaled Hosny <khaled@aliftype.com>
Date: Wed, 30 Dec 2020 23:40:25 +0200
Subject: [PATCH] [docs] Complete hb-metrics docs a bit

---
 src/hb-ot-metrics.cc | 31 ++++++++++++++++++++-----------
 src/hb-ot-metrics.h  |  3 ++-
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/src/hb-ot-metrics.cc b/src/hb-ot-metrics.cc
index 3065ea2ad..72aeff82d 100644
--- a/src/hb-ot-metrics.cc
+++ b/src/hb-ot-metrics.cc
@@ -119,11 +119,11 @@ _get_gasp (hb_face_t *face, float *result, hb_ot_metrics_tag_t metrics_tag)
 
 /**
  * hb_ot_metrics_get_position:
- * @font: a #hb_font_t object.
+ * @font: an #hb_font_t object.
  * @metrics_tag: tag of metrics value you like to fetch.
  * @position: (out) (optional): result of metrics value from the font.
  *
- * It fetches metrics value corresponding to a given tag from a font.
+ * Fetches metrics value corresponding to @metrics_tag from @font.
  *
  * Returns: Whether found the requested metrics in the font.
  * Since: 2.6.0
@@ -193,10 +193,13 @@ hb_ot_metrics_get_position (hb_font_t           *font,
 #ifndef HB_NO_VAR
 /**
  * hb_ot_metrics_get_variation:
- * @font:
- * @metrics_tag:
+ * @font: an #hb_font_t object.
+ * @metrics_tag: tag of metrics value you like to fetch.
  *
- * Returns:
+ * Fetches metrics value corresponding to @metrics_tag from @font with the
+ * current font variation settings applied.
+ *
+ * Returns: The requested metric value.
  *
  * Since: 2.6.0
  **/
@@ -208,10 +211,13 @@ hb_ot_metrics_get_variation (hb_font_t *font, hb_ot_metrics_tag_t metrics_tag)
 
 /**
  * hb_ot_metrics_get_x_variation:
- * @font:
- * @metrics_tag:
+ * @font: an #hb_font_t object.
+ * @metrics_tag: tag of metrics value you like to fetch.
  *
- * Returns:
+ * Fetches horizontal metrics value corresponding to @metrics_tag from @font
+ * with the current font variation settings applied.
+ *
+ * Returns: The requested metric value.
  *
  * Since: 2.6.0
  **/
@@ -223,10 +229,13 @@ hb_ot_metrics_get_x_variation (hb_font_t *font, hb_ot_metrics_tag_t metrics_tag)
 
 /**
  * hb_ot_metrics_get_y_variation:
- * @font:
- * @metrics_tag:
+ * @font: an #hb_font_t object.
+ * @metrics_tag: tag of metrics value you like to fetch.
  *
- * Returns:
+ * Fetches vertical metrics value corresponding to @metrics_tag from @font with
+ * the current font variation settings applied.
+ *
+ * Returns: The requested metric value.
  *
  * Since: 2.6.0
  **/
diff --git a/src/hb-ot-metrics.h b/src/hb-ot-metrics.h
index f501c63e7..2bdb6875a 100644
--- a/src/hb-ot-metrics.h
+++ b/src/hb-ot-metrics.h
@@ -66,7 +66,8 @@ HB_BEGIN_DECLS
  * @HB_OT_METRICS_TAG_UNDERLINE_SIZE: underline size.
  * @HB_OT_METRICS_TAG_UNDERLINE_OFFSET: underline offset.
  *
- * From https://docs.microsoft.com/en-us/typography/opentype/spec/mvar#value-tags
+ * Metric tags corresponding to [MVAR Value
+ * Tags](https://docs.microsoft.com/en-us/typography/opentype/spec/mvar#value-tags)
  *
  * Since: 2.6.0
  **/