Add documentation of which parts of the API are unstable

* Use secret-unstable.h header for unstable bits
 * Add stability tag to SECTION headers

docs/reference/libsecret/libsecret-docs.sgml

@@ -9,7 +9,7 @@
 		<releaseinfo>
 			for libsecret &version;.
 			An online version of this documentation can be found at
-			<ulink role="online-location" url="http://developer.gnome.org/libsecret/stable/">http://developer.gnome.org/libsecret/stable/</ulink>.
+			<ulink role="online-location" url="http://developer.gnome.org/libsecret/unstable/">http://developer.gnome.org/libsecret/unstable/</ulink>.
 		</releaseinfo>
 	</bookinfo>
 
@@ -28,6 +28,7 @@
 		<xi:include href="xml/secret-item.xml"/>
 		<xi:include href="xml/secret-value.xml"/>
 		<xi:include href="xml/secret-prompt.xml"/>
+		<xi:include href="xml/secret-schema.xml"/>
 		<xi:include href="xml/secret-error.xml"/>
 	</part>
 

docs/reference/libsecret/libsecret-sections.txt

@@ -1,5 +1,6 @@
 <SECTION>
 <FILE>secret-collection</FILE>
+<INCLUDE>secret/secret-unstable.h</INCLUDE>
 SecretCollection
 SecretCollectionClass
 secret_collection_new
@@ -33,6 +34,7 @@ secret_collection_get_type
 
 <SECTION>
 <FILE>secret-item</FILE>
+<INCLUDE>secret/secret-unstable.h</INCLUDE>
 SecretItem
 SecretItemClass
 secret_item_new
@@ -75,6 +77,7 @@ secret_item_get_type
 
 <SECTION>
 <FILE>secret-error</FILE>
+<INCLUDE>secret/secret.h</INCLUDE>
 SECRET_ERROR
 SecretError
 <SUBSECTION Standard>
@@ -85,6 +88,7 @@ secret_error_get_type
 
 <SECTION>
 <FILE>secret-password</FILE>
+<INCLUDE>secret/secret.h</INCLUDE>
 SECRET_COLLECTION_DEFAULT
 SECRET_COLLECTION_SESSION
 secret_password_store
@@ -111,6 +115,7 @@ secret_password_free
 
 <SECTION>
 <FILE>secret-schema</FILE>
+<INCLUDE>secret/secret.h</INCLUDE>
 SecretSchema
 SecretSchemaFlags
 SecretSchemaAttribute
@@ -130,6 +135,7 @@ SECRET_SCHEMA_COMPAT_NETWORK
 
 <SECTION>
 <FILE>secret-prompt</FILE>
+<INCLUDE>secret/secret-unstable.h</INCLUDE>
 SecretPrompt
 SecretPromptClass
 secret_prompt_get_result_value
@@ -150,6 +156,7 @@ secret_prompt_get_type
 
 <SECTION>
 <FILE>secret-service</FILE>
+<INCLUDE>secret/secret-unstable.h</INCLUDE>
 SecretService
 SecretServiceClass
 SecretServiceFlags
@@ -238,6 +245,7 @@ secret_service_get_type
 
 <SECTION>
 <FILE>secret-value</FILE>
+<INCLUDE>secret/secret-unstable.h</INCLUDE>
 SecretValue
 secret_value_new
 secret_value_new_full

library/Makefile.am

@@ -30,6 +30,7 @@ HEADER_FILES = \
 	secret-schemas.h \
 	secret-service.h \
 	secret-types.h \
+	secret-unstable.h \
 	secret-value.h \
 	$(NULL)
 

library/secret-collection.c

@@ -35,6 +35,8 @@
  * Use the SecretCollection::items property or secret_collection_get_items() to
  * lookup the items in the collection. There may not be any items exposed when
  * the collection is locked.
+ *
+ * @stability: Unstable
  */
 
 /**

library/secret-collection.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_COLLECTION_H__

library/secret-item.c

@@ -45,6 +45,8 @@
  * the attributes associated with an item.
  *
  * Items can be created with secret_item_create() or secret_service_store().
+ *
+ * @stability: Unstable
  */
 
 /**

library/secret-item.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_ITEM_H__

library/secret-password.c

@@ -35,6 +35,8 @@
  *
  * Each of the functions accept a variable list of attributes names and their
  * values. Include a %NULL to terminate the list of attributes.
+ *
+ * @stability: Stable
  */
 
 typedef struct {

library/secret-password.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_PASSWORD_H__

library/secret-prompt.c

@@ -35,6 +35,8 @@
  * In order to customize prompt handling, override the
  * SecretServiceClass::prompt_async and SecretServiceClass::prompt_finish
  * virtual methods of the #SecretService class.
+ *
+ * @stability: Unstable
  */
 
 /**

library/secret-prompt.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_PROMPT_H__

library/secret-schema.c

@@ -56,7 +56,9 @@
  * 	};
  * 	return &the_schema;
  * }
- * </programlisting></informalexample>s
+ * </programlisting></informalexample>
+ *
+ * @stability: Stable
  */
 
 /**
@@ -84,6 +86,8 @@
  * 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.
+ *
+ * @stability: Stable
  */
 
 /**

library/secret-schema.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_SCHEMA_H__

library/secret-schemas.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_SCHEMAS_H__

library/secret-service.c

@@ -62,6 +62,8 @@
  *
  * In order to customize prompt handling, override the <literal>prompt_async</literal>
  * and <literal>prompt_finish</literal> virtual methods of the #SecretService class.
+ *
+ * @stability: Unstable
  */
 
 /**

library/secret-service.h

@@ -12,7 +12,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_SERVICE_H__

library/secret-types.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_TYPES_H__

library/secret-unstable.h

@@ -0,0 +1,36 @@
+/* libsecret - GLib wrapper for Secret Service
+ *
+ * Copyright 2012 Red Hat Inc.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation; either version 2 of the licence or (at
+ * your option) any later version.
+ *
+ * See the included COPYING file for more information.
+ */
+
+#ifndef SECRET_API_SUBJECT_TO_CHANGE
+#error "This API has not yet reached stability. Define SECRET_API_SUBJECT_TO_CHANGE to acknowledge"
+#endif
+
+#ifndef __SECRET_UNSTABLE_H__
+#define __SECRET_UNSTABLE_H__
+
+#include <glib.h>
+
+#include <secret.h>
+
+#define __SECRET_INSIDE_HEADER__
+
+#include <secret/secret-collection.h>
+#include <secret/secret-enum-types.h>
+#include <secret/secret-item.h>
+#include <secret/secret-prompt.h>
+#include <secret/secret-schemas.h>
+#include <secret/secret-service.h>
+#include <secret/secret-value.h>
+
+#undef __SECRET_INSIDE_HEADER__
+
+#endif /* __SECRET_UNSTABLE_H__ */

library/secret-util.c

@@ -17,6 +17,18 @@
 
 #include <string.h>
 
+/**
+ * SECTION:secret-error
+ * @title: SecretError
+ * @short_description: libsecret errors
+ *
+ * Various errors reported by the libsecret library. No error returned from
+ * the libsecret API is suitable for direct display to the user. It is up
+ * to the application to handle them appropriately.
+ *
+ * @stability: Stable
+ */
+
 /**
  * SecretError:
  * @SECRET_ERROR_PROTOCOL: received an invalid data or message from the Secret

library/secret-value.c

@@ -35,6 +35,8 @@
  *
  * #SecretValue is reference counted and immutable. The secret data is only
  * freed when all references have been released via secret_value_unref().
+ *
+ * @stability: Unstable
  */
 
 /**

library/secret-value.h

@@ -11,7 +11,7 @@
  */
 
 #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
-#error "Only <secret/secret.h> can be included directly."
+#error "Only <secret/secret.h> or <secret/secret-unstable.h> can be included directly."
 #endif
 
 #ifndef __SECRET_VALUE_H__

library/secret.h

@@ -10,10 +10,6 @@
  * See the included COPYING file for more information.
  */
 
-#ifndef SECRET_API_SUBJECT_TO_CHANGE
-#error "This API has not yet reached stability."
-#endif
-
 #ifndef __SECRET_H__
 #define __SECRET_H__
 
@@ -21,15 +17,9 @@
 
 #define __SECRET_INSIDE_HEADER__
 
-#include <secret/secret-collection.h>
-#include <secret/secret-enum-types.h>
-#include <secret/secret-item.h>
 #include <secret/secret-password.h>
-#include <secret/secret-prompt.h>
 #include <secret/secret-schema.h>
-#include <secret/secret-schemas.h>
+#include <secret/secret-types.h>
-#include <secret/secret-service.h>
-#include <secret/secret-value.h>
 
 #undef __SECRET_INSIDE_HEADER__