1 files changed, 72 insertions, 6 deletions
diff --git a/libsecret/secret-schema.c b/libsecret/secret-schema.c
index 32967bf..7e21106 100644
--- a/libsecret/secret-schema.c
+++ b/libsecret/secret-schema.c
@@ -23,10 +23,73 @@
 #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
  * @SECRET_SCHEMA_DONT_MATCH_NAME: don't match the schema name when looking up or
- *                                 removing passwords
+ *   removing passwords
  *
  * Flags for a #SecretSchema definition.
  */
@@ -45,9 +108,11 @@
  * @SECRET_SCHEMA_ATTRIBUTE_INTEGER: an integer attribute, stored as a decimal
  * @SECRET_SCHEMA_ATTRIBUTE_STRING: a utf-8 string attribute
  *
- * The type of an attribute in a #SecretSchema. 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.
+ * The type of an attribute in a [struct@SecretSchema].
+ *
+ * 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.
  */
 
 static SecretSchemaAttribute *
@@ -269,8 +334,9 @@ _secret_schema_ref_if_nonstatic (const SecretSchema *schema)
  * secret_schema_unref:
  * @schema: the schema to reference
  *
- * Releases a reference to the #SecretSchema. If the last reference is
- * released then the schema will be freed.
+ * Releases a reference to the #SecretSchema.
+ *
+ * If the last reference is released then the schema will be freed.
  *
  * It is not normally necessary to call this function from C code, and is
  * mainly present for the sake of bindings. It is an error to call this for