From 48f8ed7e0205e1c0dcf0a19c1bfc9b515182563a Mon Sep 17 00:00:00 2001
From: Behdad Esfahbod <behdad@behdad.org>
Date: Sat, 22 Apr 2023 10:11:22 -0600
Subject: [PATCH] Docs

---
 src/hb-buffer.cc    | 5 +++++
 src/hb-face.cc      | 6 ++++++
 src/hb-font.cc      | 5 +++++
 src/hb-ot-layout.cc | 2 ++
 4 files changed, 18 insertions(+)

diff --git a/src/hb-buffer.cc b/src/hb-buffer.cc
index f557ceee5..616cee807 100644
--- a/src/hb-buffer.cc
+++ b/src/hb-buffer.cc
@@ -40,6 +40,11 @@
  * Buffers serve a dual role in HarfBuzz; before shaping, they hold
  * the input characters that are passed to hb_shape(), and after
  * shaping they hold the output glyphs.
+ *
+ * The input buffer is a sequence of Unicode codepoints, with
+ * associated attributes such as direction and script.  The output
+ * buffer is a sequence of glyphs, with associated attributes such
+ * as position and cluster.
  **/
 
 
diff --git a/src/hb-face.cc b/src/hb-face.cc
index f6ca19fac..e34071058 100644
--- a/src/hb-face.cc
+++ b/src/hb-face.cc
@@ -47,6 +47,12 @@
  * More precisely, a font face represents a single face in a binary font file.
  * Font faces are typically built from a binary blob and a face index.
  * Font faces are used to create fonts.
+ *
+ * A font face can be created from a binary blob using hb_face_create().
+ * The face index is used to select a face from a binary blob that contains
+ * multiple faces.  For example, a binary blob that contains both a regular
+ * and a bold face can be used to create two font faces, one for each face
+ * index.
  **/
 
 
diff --git a/src/hb-font.cc b/src/hb-font.cc
index 4c8727f21..688513112 100644
--- a/src/hb-font.cc
+++ b/src/hb-font.cc
@@ -59,6 +59,11 @@
  *
  * HarfBuzz provides a built-in set of lightweight default
  * functions for each method in #hb_font_funcs_t.
+ *
+ * The default font functions are implemented in terms of the
+ * #hb_font_funcs_t methods of the parent font object.  This allows
+ * client programs to override only the methods they need to, and
+ * otherwise inherit the parent font's implementation, if any.
  **/
 
 
diff --git a/src/hb-ot-layout.cc b/src/hb-ot-layout.cc
index 6c4055e04..256a05586 100644
--- a/src/hb-ot-layout.cc
+++ b/src/hb-ot-layout.cc
@@ -64,6 +64,8 @@ using OT::Layout::GPOS;
  * @include: hb-ot.h
  *
  * Functions for querying OpenType Layout features in the font face.
+ * See the <ulink url="http://www.microsoft.com/typography/otspec/">OpenType
+ * specification</ulink> for details.
  **/