Commit ebb28069 authored by Stef Walter's avatar Stef Walter
Browse files

Add documentation of which parts of the API are unstable

 * Use secret-unstable.h header for unstable bits
 * Add stability tag to SECTION headers
parent 8417d8c9
......@@ -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>
......
<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
......
......@@ -30,6 +30,7 @@ HEADER_FILES = \
secret-schemas.h \
secret-service.h \
secret-types.h \
secret-unstable.h \
secret-value.h \
$(NULL)
......
......@@ -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
*/
/**
......
......@@ -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__
......
......@@ -45,6 +45,8 @@
* the attributes associated with an item.
*
* Items can be created with secret_item_create() or secret_service_store().
*
* @stability: Unstable
*/
/**
......
......@@ -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__
......
......@@ -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 {
......
......@@ -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__
......
......@@ -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
*/
/**
......
......@@ -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__
......
......@@ -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
*/
/**
......
......@@ -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__
......
......@@ -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__
......
......@@ -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
*/
/**
......
......@@ -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__
......
......@@ -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__
......
/* 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__ */
......@@ -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
......
......@@ -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
*/
/**
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment