diff --git a/src/hb-map.cc b/src/hb-map.cc
index 225f37bc6..57d17ba1e 100644
--- a/src/hb-map.cc
+++ b/src/hb-map.cc
@@ -27,7 +27,16 @@
 #include "hb-map.hh"
 
 
-/* Public API */
+/**
+ * SECTION:hb-map
+ * @title: Map
+ * @short_description: Object representing integer to integer mapping
+ * @include: hb.h
+ *
+ * Map objects are integer-to-integer hash-maps.  Currently they are
+ * not used in the HarfBuzz public API, but are provided for client's
+ * use if desired.
+ **/
 
 
 /**
diff --git a/src/hb-set.cc b/src/hb-set.cc
index 25c19147f..8b1a359c5 100644
--- a/src/hb-set.cc
+++ b/src/hb-set.cc
@@ -27,7 +27,16 @@
 #include "hb-set.hh"
 
 
-/* Public API */
+/**
+ * SECTION:hb-set
+ * @title: Set
+ * @short_description: Object representing a set of integers
+ * @include: hb.h
+ *
+ * Set objects represent a mathematical set of integer values.  They are
+ * used in non-shaping API to query certain set of characters or glyphs,
+ * or other integer values.
+ **/
 
 
 /**