From ebb280694664dae9a773babe3fd5e869e1a8e203 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Sat, 24 Mar 2012 07:52:12 +0100 Subject: [PATCH] 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 | 3 +- .../libsecret/libsecret-sections.txt | 8 +++++ library/Makefile.am | 1 + library/secret-collection.c | 2 ++ library/secret-collection.h | 2 +- library/secret-item.c | 2 ++ library/secret-item.h | 2 +- library/secret-password.c | 2 ++ library/secret-password.h | 2 +- library/secret-prompt.c | 2 ++ library/secret-prompt.h | 2 +- library/secret-schema.c | 6 +++- library/secret-schema.h | 2 +- library/secret-schemas.h | 2 +- library/secret-service.c | 2 ++ library/secret-service.h | 2 +- library/secret-types.h | 2 +- library/secret-unstable.h | 36 +++++++++++++++++++ library/secret-util.c | 12 +++++++ library/secret-value.c | 2 ++ library/secret-value.h | 2 +- library/secret.h | 12 +------ 22 files changed, 86 insertions(+), 22 deletions(-) create mode 100644 library/secret-unstable.h diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml index 1172dfb..ce974a6 100644 --- a/docs/reference/libsecret/libsecret-docs.sgml +++ b/docs/reference/libsecret/libsecret-docs.sgml @@ -9,7 +9,7 @@ for libsecret &version;. An online version of this documentation can be found at - http://developer.gnome.org/libsecret/stable/. + http://developer.gnome.org/libsecret/unstable/. @@ -28,6 +28,7 @@ + diff --git a/docs/reference/libsecret/libsecret-sections.txt b/docs/reference/libsecret/libsecret-sections.txt index 15cb5f7..a26fb83 100644 --- a/docs/reference/libsecret/libsecret-sections.txt +++ b/docs/reference/libsecret/libsecret-sections.txt @@ -1,5 +1,6 @@
secret-collection +secret/secret-unstable.h SecretCollection SecretCollectionClass secret_collection_new @@ -33,6 +34,7 @@ secret_collection_get_type
secret-item +secret/secret-unstable.h SecretItem SecretItemClass secret_item_new @@ -75,6 +77,7 @@ secret_item_get_type
secret-error +secret/secret.h SECRET_ERROR SecretError @@ -85,6 +88,7 @@ secret_error_get_type
secret-password +secret/secret.h SECRET_COLLECTION_DEFAULT SECRET_COLLECTION_SESSION secret_password_store @@ -111,6 +115,7 @@ secret_password_free
secret-schema +secret/secret.h SecretSchema SecretSchemaFlags SecretSchemaAttribute @@ -130,6 +135,7 @@ SECRET_SCHEMA_COMPAT_NETWORK
secret-prompt +secret/secret-unstable.h SecretPrompt SecretPromptClass secret_prompt_get_result_value @@ -150,6 +156,7 @@ secret_prompt_get_type
secret-service +secret/secret-unstable.h SecretService SecretServiceClass SecretServiceFlags @@ -238,6 +245,7 @@ secret_service_get_type
secret-value +secret/secret-unstable.h SecretValue secret_value_new secret_value_new_full diff --git a/library/Makefile.am b/library/Makefile.am index fcddb01..af807a6 100644 --- a/library/Makefile.am +++ b/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) diff --git a/library/secret-collection.c b/library/secret-collection.c index 50dd2e0..ce3354c 100644 --- a/library/secret-collection.c +++ b/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 */ /** diff --git a/library/secret-collection.h b/library/secret-collection.h index 34426e3..63da980 100644 --- a/library/secret-collection.h +++ b/library/secret-collection.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_COLLECTION_H__ diff --git a/library/secret-item.c b/library/secret-item.c index b1e297f..4ad21cc 100644 --- a/library/secret-item.c +++ b/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 */ /** diff --git a/library/secret-item.h b/library/secret-item.h index 21b8e8a..6a8fc2c 100644 --- a/library/secret-item.h +++ b/library/secret-item.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_ITEM_H__ diff --git a/library/secret-password.c b/library/secret-password.c index d832fbb..62c80f9 100644 --- a/library/secret-password.c +++ b/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 { diff --git a/library/secret-password.h b/library/secret-password.h index 56ed05b..8c95b6e 100644 --- a/library/secret-password.h +++ b/library/secret-password.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_PASSWORD_H__ diff --git a/library/secret-prompt.c b/library/secret-prompt.c index 4f3e0bb..8891740 100644 --- a/library/secret-prompt.c +++ b/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 */ /** diff --git a/library/secret-prompt.h b/library/secret-prompt.h index 5817378..ccb1539 100644 --- a/library/secret-prompt.h +++ b/library/secret-prompt.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_PROMPT_H__ diff --git a/library/secret-schema.c b/library/secret-schema.c index 3c18716..3683645 100644 --- a/library/secret-schema.c +++ b/library/secret-schema.c @@ -56,7 +56,9 @@ * }; * return &the_schema; * } - * s + * + * + * @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 */ /** diff --git a/library/secret-schema.h b/library/secret-schema.h index 8298ff1..f5c181c 100644 --- a/library/secret-schema.h +++ b/library/secret-schema.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_SCHEMA_H__ diff --git a/library/secret-schemas.h b/library/secret-schemas.h index 2eb55fc..cf0bfcd 100644 --- a/library/secret-schemas.h +++ b/library/secret-schemas.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_SCHEMAS_H__ diff --git a/library/secret-service.c b/library/secret-service.c index accf9e5..50d6c6e 100644 --- a/library/secret-service.c +++ b/library/secret-service.c @@ -62,6 +62,8 @@ * * In order to customize prompt handling, override the prompt_async * and prompt_finish virtual methods of the #SecretService class. + * + * @stability: Unstable */ /** diff --git a/library/secret-service.h b/library/secret-service.h index 32b0a8e..6cb2143 100644 --- a/library/secret-service.h +++ b/library/secret-service.h @@ -12,7 +12,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_SERVICE_H__ diff --git a/library/secret-types.h b/library/secret-types.h index c7f61fa..d278a88 100644 --- a/library/secret-types.h +++ b/library/secret-types.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_TYPES_H__ diff --git a/library/secret-unstable.h b/library/secret-unstable.h new file mode 100644 index 0000000..a2b84b7 --- /dev/null +++ b/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 + +#include + +#define __SECRET_INSIDE_HEADER__ + +#include +#include +#include +#include +#include +#include +#include + +#undef __SECRET_INSIDE_HEADER__ + +#endif /* __SECRET_UNSTABLE_H__ */ diff --git a/library/secret-util.c b/library/secret-util.c index c193057..5834916 100644 --- a/library/secret-util.c +++ b/library/secret-util.c @@ -17,6 +17,18 @@ #include +/** + * 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 diff --git a/library/secret-value.c b/library/secret-value.c index 07220f1..b0aa293 100644 --- a/library/secret-value.c +++ b/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 */ /** diff --git a/library/secret-value.h b/library/secret-value.h index bc1b6cb..d048302 100644 --- a/library/secret-value.h +++ b/library/secret-value.h @@ -11,7 +11,7 @@ */ #if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) -#error "Only can be included directly." +#error "Only or can be included directly." #endif #ifndef __SECRET_VALUE_H__ diff --git a/library/secret.h b/library/secret.h index 62ba243..9aeb758 100644 --- a/library/secret.h +++ b/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 -#include -#include #include -#include #include -#include -#include -#include +#include #undef __SECRET_INSIDE_HEADER__