diff --git a/src/hb-blob.cc b/src/hb-blob.cc
index 521e8b693..51f22ce4d 100644
--- a/src/hb-blob.cc
+++ b/src/hb-blob.cc
@@ -42,7 +42,7 @@
 
 /**
  * SECTION: hb-blob
- * @title: hb_blob_t
+ * @title: hb-blob
  * @short_description: Binary data containers
  * @include: hb.h
  *
diff --git a/src/hb-buffer.cc b/src/hb-buffer.cc
index d773dd84a..5a8152ed4 100644
--- a/src/hb-buffer.cc
+++ b/src/hb-buffer.cc
@@ -33,7 +33,7 @@
 
 /**
  * SECTION: hb-buffer
- * @title: hb_buffer_t
+ * @title: hb-buffer
  * @short_description: Input and output buffers
  * @include: hb.h
  *
diff --git a/src/hb-common.cc b/src/hb-common.cc
index 2a61fcc33..d7c1921f3 100644
--- a/src/hb-common.cc
+++ b/src/hb-common.cc
@@ -38,7 +38,7 @@
 
 /**
  * SECTION:hb-common
- * @title: Common types
+ * @title: hb-common
  * @short_description: Common data types
  * @include: hb.h
  *
@@ -628,7 +628,7 @@ hb_user_data_array_t::get (hb_user_data_key_t *key)
 
 /**
  * SECTION:hb-version
- * @title: Version
+ * @title: hb-version
  * @short_description: Information about the version of HarfBuzz in use
  * @include: hb.h
  *
diff --git a/src/hb-deprecated.h b/src/hb-deprecated.h
index 369d07361..e39b79f74 100644
--- a/src/hb-deprecated.h
+++ b/src/hb-deprecated.h
@@ -36,6 +36,18 @@
 #include "hb-font.h"
 #include "hb-set.h"
 
+
+/**
+ * SECTION:hb-deprecated
+ * @title: hb-deprecated
+ * @short_description: Deprecated API
+ * @include: hb.h
+ *
+ * These API have been deprecated in favor of newer API, or because they
+ * were deemed unnecessary.
+ **/
+
+
 HB_BEGIN_DECLS
 
 #ifndef HB_DISABLE_DEPRECATED
diff --git a/src/hb-face.cc b/src/hb-face.cc
index 2f6ccea31..7ca4b1ba2 100644
--- a/src/hb-face.cc
+++ b/src/hb-face.cc
@@ -37,7 +37,7 @@
 
 /**
  * SECTION:hb-face
- * @title: hb_face_t
+ * @title: hb-face
  * @short_description: Font face objects
  * @include: hb.h
  *
diff --git a/src/hb-font.cc b/src/hb-font.cc
index 2ef0ff854..135d310ca 100644
--- a/src/hb-font.cc
+++ b/src/hb-font.cc
@@ -36,7 +36,7 @@
 
 /**
  * SECTION:hb-font
- * @title: hb_font_t
+ * @title: hb-font
  * @short_description: Font objects
  * @include: hb.h
  *
diff --git a/src/hb-shape.cc b/src/hb-shape.cc
index 00c61397e..f98bc6e51 100644
--- a/src/hb-shape.cc
+++ b/src/hb-shape.cc
@@ -37,7 +37,7 @@
 
 /**
  * SECTION:hb-shape
- * @title: Shaping
+ * @title: hb-shape
  * @short_description: Conversion of text strings into positioned glyphs
  * @include: hb.h
  *
diff --git a/src/hb-unicode.cc b/src/hb-unicode.cc
index ca555a8df..cba18ab6a 100644
--- a/src/hb-unicode.cc
+++ b/src/hb-unicode.cc
@@ -35,7 +35,7 @@
 
 /**
  * SECTION: hb-unicode
- * @title: hb_unicode_funcs_t
+ * @title: hb-unicode
  * @short_description: Unicode character property access
  * @include: hb.h
  *