diff --git a/docs/reference/libsecret/libsecret-simple-api.md b/docs/reference/libsecret/libsecret-simple-api.md
index b6fda5e..11cf8fe 100644
--- a/docs/reference/libsecret/libsecret-simple-api.md
+++ b/docs/reference/libsecret/libsecret-simple-api.md
@@ -20,61 +20,6 @@ the [struct@Schema] structure.
 Each of the functions accept a variable list of attributes names and their
 values. Include a `NULL` to terminate the list of attributes.
 
-## SecretSchema
-
-Represents a set of attributes that are stored with an item. These schemas are
-used for interoperability between various services storing the same types of
-items.
-
-Each schema has a name like `org.gnome.keyring.NetworkPassword`, and defines a
-set of attributes, and types (string, integer, boolean) for those attributes.
-
-Attributes are stored as strings in the Secret Service, and the attribute types
-simply define standard ways to store integer and boolean values as strings.
-Attributes are represented in libsecret via a [struct@GLib.HashTable] with
-string keys and values. Even for values that defined as an integer or boolean in
-the schema, the attribute values in the [struct@GLib.HashTable] are strings.
-Boolean values are stored as the strings 'true' and 'false'. Integer values are
-stored in decimal, with a preceding negative sign for negative integers.
-
-Schemas are handled entirely on the client side by this library. The name of the
-schema is automatically stored as an attribute on the item.
-
-Normally when looking up passwords only those with matching schema names are
-returned. If the schema @flags contain the `SECRET_SCHEMA_DONT_MATCH_NAME` flag,
-then lookups will not check that the schema name matches that on the item, only
-the schema's attributes are matched. This is useful when you are looking up
-items that are not stored by the libsecret library. Other libraries such as
-libgnome-keyring don't store the schema name.
-
-Additional schemas can be defined via the %SecretSchema structure like this:
-
-```c
-// in a header:
-
-const SecretSchema * example_get_schema (void) G_GNUC_CONST;
-
-#define EXAMPLE_SCHEMA  example_get_schema ()
-
-
-// in a .c file
-
-const SecretSchema *
-example_get_schema (void)
-{
-    static const SecretSchema the_schema = {
-        "org.example.Password", SECRET_SCHEMA_NONE,
-        {
-            {  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
-            {  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
-            {  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
-            {  NULL, 0 },
-        }
-    };
-    return &the_schema;
-}
-```
-
 ## Secret Attributes
 
 Each item has a set of attributes, which are used to locate the item later.
diff --git a/libsecret/secret-schema.c b/libsecret/secret-schema.c
index 32967bf..3c7f51a 100644
--- a/libsecret/secret-schema.c
+++ b/libsecret/secret-schema.c
@@ -22,6 +22,69 @@
 
 #include "egg/egg-secure-memory.h"
 
+/**
+ * SecretSchema:
+ * @name: the dotted name of the schema
+ * @flags: flags for the schema
+ * @attributes:  the attribute names and types of those attributes
+ *
+ * Represents a set of attributes that are stored with an item.
+ *
+ * These schemas are used for interoperability between various services storing
+ * the same types of items.
+ *
+ * Each schema has a name like `org.gnome.keyring.NetworkPassword`, and defines a
+ * set of attributes, and types (string, integer, boolean) for those attributes.
+ *
+ * Attributes are stored as strings in the Secret Service, and the attribute types
+ * simply define standard ways to store integer and boolean values as strings.
+ * Attributes are represented in libsecret via a [struct@GLib.HashTable] with
+ * string keys and values. Even for values that defined as an integer or boolean in
+ * the schema, the attribute values in the [struct@GLib.HashTable] are strings.
+ * Boolean values are stored as the strings 'true' and 'false'. Integer values are
+ * stored in decimal, with a preceding negative sign for negative integers.
+ *
+ * Schemas are handled entirely on the client side by this library. The name of the
+ * schema is automatically stored as an attribute on the item.
+ *
+ * Normally when looking up passwords only those with matching schema names are
+ * returned. If the schema @flags contain the `SECRET_SCHEMA_DONT_MATCH_NAME` flag,
+ * then lookups will not check that the schema name matches that on the item, only
+ * the schema's attributes are matched. This is useful when you are looking up
+ * items that are not stored by the libsecret library. Other libraries such as
+ * libgnome-keyring don't store the schema name.
+ *
+ * Additional schemas can be defined via the %SecretSchema structure like this:
+ *
+ * ```c
+ * // in a header:
+ *
+ * const SecretSchema * example_get_schema (void) G_GNUC_CONST;
+ *
+ * #define EXAMPLE_SCHEMA  example_get_schema ()
+ *
+ *
+ * // in a .c file
+ *
+ * const SecretSchema *
+ * example_get_schema (void)
+ * {
+ *     static const SecretSchema the_schema = {
+ *         "org.example.Password", SECRET_SCHEMA_NONE,
+ *         {
+ *             {  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
+ *             {  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
+ *             {  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
+ *             {  NULL, 0 },
+ *         }
+ *     };
+ *     return &the_schema;
+ * }
+ * ```
+ *
+ * Stability: Stable
+ */
+
 /**
  * SecretSchemaFlags:
  * @SECRET_SCHEMA_NONE: no flags for the schema