Upgrading to GitLab 12.1.0.

Commit 53aefd8c authored by Adam Schreiber's avatar Adam Schreiber

Bug 585538 - Add GTK-Doc comments

Fix gtk-doc warnings
parent 9789966d
......@@ -44,6 +44,13 @@
#include "pgp/seahorse-server-source.h"
#endif
/**
* SECTION:seahorse-context
* @short_description: This is where all the action in a Seahorse process comes together.
* @include:libseahorse/seahorse-context.h
*
**/
/* The application main context */
SeahorseContext* app_context = NULL;
......@@ -776,10 +783,12 @@ seahorse_context_remove_object (SeahorseContext *sctx, SeahorseObject *sobj)
*/
/**
* seahorse_context_get_default_key
* seahorse_context_get_default_key:
* @sctx: Current #SeahorseContext
*
* Returns: the secret key that's the default key
*
* Returns: the secret key that's the default key
*
* Deprecated: No replacement
*/
SeahorseObject*
seahorse_context_get_default_key (SeahorseContext *sctx)
......@@ -805,12 +814,14 @@ seahorse_context_get_default_key (SeahorseContext *sctx)
}
/**
* seahorse_context_get_discovery
* seahorse_context_get_discovery:
* @sctx: #SeahorseContext object
*
*
* Gets the Service Discovery object for this context.
*
* Return: The Service Discovery object.
* Returns: The Service Discovery object.
*
* Deprecated: No replacement
*/
SeahorseServiceDiscovery*
seahorse_context_get_discovery (SeahorseContext *sctx)
......
......@@ -20,24 +20,6 @@
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseContext: This is where all the action in a Seahorse process comes
* together.
*
* - Usually there's only one SeahorseContext per process created by passing
* |SEAHORSE_CONTEXT_APP| to |seahorse_context_new|, and accessed via
* the |SCTX_APP| macro.
* - Retains the list of all valid struct _SeahorseObject objects.
* - Has a collection of SeahorseSource objects which add objects to the
* SeahorseContext.
*
* Signals:
* added: A object was added to the context.
* removed: A object was removed from the context.
* changed: A object changed.
* destroy: The context was destroyed.
*/
#ifndef __SEAHORSE_CONTEXT_H__
#define __SEAHORSE_CONTEXT_H__
......@@ -61,6 +43,28 @@ typedef struct _SeahorseContext SeahorseContext;
typedef struct _SeahorseContextClass SeahorseContextClass;
typedef struct _SeahorseContextPrivate SeahorseContextPrivate;
/**
* SeahorseContext:
* @parent: The parent #GtkObject
* @is_daemon: a #gboolean indicating whether the context is being used in a
* program that is daemonized
*
* This is where all the action in a Seahorse process comes together.
*
* - Usually there's only one #SeahorseContext per process created by passing
* %SEAHORSE_CONTEXT_APP to seahorse_context_new(), and accessed via
* the %SCTX_APP macro.
* - Retains the list of all valid struct _SeahorseObject objects.
* - Has a collection of #SeahorseSource objects which add objects to the
* #SeahorseContext.
*
* Signals:
* added: A object was added to the context.
* removed: A object was removed from the context.
* changed: A object changed.
* destroy: The context was destroyed.
*/
struct _SeahorseContext {
GtkObject parent;
......
......@@ -18,15 +18,6 @@
* 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseServiceDiscovery: Listens for DNS-SD shared keys on the network and
* adds SeahorseKeySoruce objects to the SeahorseContext as necessary.
*
* Signals:
* added: A new shared key source was found.
* removed: A shared key source went away.
*/
#ifndef __SEAHORSE_DNS_SD_H__
#define __SEAHORSE_DNS_SD_H__
......@@ -44,6 +35,19 @@ typedef struct _SeahorseServiceDiscovery SeahorseServiceDiscovery;
typedef struct _SeahorseServiceDiscoveryClass SeahorseServiceDiscoveryClass;
typedef struct _SeahorseServiceDiscoveryPriv SeahorseServiceDiscoveryPriv;
/**
* SeahorseServiceDiscovery:
* @parent: The parent #GObject
* @services: A #GHashTable of known services
*
* Listens for DNS-SD shared keys on the network and
* adds SeahorseKeySoruce objects to the SeahorseContext as necessary.
*
* Signals:
* added: A new shared key source was found.
* removed: A shared key source went away.
*/
struct _SeahorseServiceDiscovery {
GObject parent;
......
......@@ -18,17 +18,6 @@
* 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseKeyServerControl: A control which allows you to select from a set
* of keyservers.
*
* - Also displays shares for keys found via DNS-SD over the network.
*
* Properties:
* gconf-key: (gchar*) The GConf key to retrieve and set keyservers.
* none-option: (gchar*) Text to display for 'no key server'
*/
#ifndef __SEAHORSE_KEYSERVER_CONTROL_H__
#define __SEAHORSE_KEYSERVER_CONTROL_H__
......@@ -45,6 +34,20 @@
typedef struct _SeahorseKeyserverControl SeahorseKeyserverControl;
typedef struct _SeahorseKeyserverControlClass SeahorseKeyserverControlClass;
/**
* SeahorseKeyServerControl:
* @parent_instance: The parent #GtkComboBox
*
* A control which allows you to select from a set
* of keyservers.
*
* - Also displays shares for keys found via DNS-SD over the network.
*
* Properties:
* gconf-key: (gchar*) The GConf key to retrieve and set keyservers.
* none-option: (gchar*) Text to display for 'no key server'
*/
struct _SeahorseKeyserverControl {
GtkComboBox parent_instance;
......
......@@ -18,14 +18,6 @@
* 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseObjectModel: A GtkTreeModel that can assign certain rows as
* 'key rows' which are updated when a key is updated.
*
* Signals:
* update-row: A request to update a row
*/
#ifndef __SEAHORSE_OBJECT_MODEL_H__
#define __SEAHORSE_OBJECT_MODEL_H__
......@@ -43,7 +35,18 @@
typedef struct _SeahorseObjectModel SeahorseObjectModel;
typedef struct _SeahorseObjectModelClass SeahorseObjectModelClass;
/**
* SeahorseObjectModel:
* @parent: The parent #GtkTreeStore
*
* A GtkTreeModel that can assign certain rows as
* 'key rows' which are updated when a key is updated.
*
* Signals:
* update-row: A request to update a row
*/
struct _SeahorseObjectModel {
GtkTreeStore parent;
};
......
......@@ -31,6 +31,7 @@
#include <glib/gi18n.h>
/**
* _SeahorseObjectProps:
* @PROP_0:
* @PROP_CONTEXT:
* @PROP_SOURCE:
......@@ -48,7 +49,7 @@
* @PROP_USAGE:
* @PROP_FLAGS:
*/
enum {
enum _SeahorseObjectProps {
PROP_0,
PROP_CONTEXT,
PROP_SOURCE,
......
......@@ -19,45 +19,54 @@
* Boston, MA 02111-1307, USA.
*/
#ifndef __SEAHORSE_OPERATION_H__
#define __SEAHORSE_OPERATION_H__
#include <glib-object.h>
#include <gtk/gtk.h>
#define SEAHORSE_TYPE_OPERATION (seahorse_operation_get_type ())
#define SEAHORSE_OPERATION(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), SEAHORSE_TYPE_OPERATION, SeahorseOperation))
#define SEAHORSE_OPERATION_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), SEAHORSE_TYPE_OPERATION, SeahorseOperationClass))
#define SEAHORSE_IS_OPERATION(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SEAHORSE_TYPE_OPERATION))
#define SEAHORSE_IS_OPERATION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), SEAHORSE_TYPE_OPERATION))
#define SEAHORSE_OPERATION_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SEAHORSE_TYPE_OPERATION, SeahorseOperationClass))
struct _SeahorseOperation;
/**
* SeahorseOperation: An operation taking place over time.
*
* - Generally this class is derived and a base class actually hooks in and
* SeahorseOperation:
* @parent: The parent #GObject
* @message: Progress status details ie: "foobar.jpg"
* @progress: The current progress position, -1 for indeterminate
* @is_running: If the operation is running or not
* @is_done: Operation is done or not
* @is_cancelled: Operation is cancelled or not
* @error: #GError for the operation
*
* An operation taking place over time.
*
* - Generally this class is derived and a base class actually hooks in and
* performs the operation, keeps the properties updated etc...
* - Used all over to represent things like key loading operations, search
* - Used all over to represent things like key loading operations, search
* - SeahorseMultiOperation allows you to combine multiple operations into
* a single one. Used when searching multiple key servers for example.
* - Can be tied to a progress bar (see seahorse-progress.h)
* - Holds a reference to itself while the operation is in progress.
* - The seahorse_operation_mark_* are used by derived classes to update
* - The seahorse_operation_mark_* are used by derived classes to update
* properties of the operation as things progress.
*
* Signals:
* done: The operation is complete.
* progress: The operation has progressed, or changed state somehow.
*
*
* Properties:
* result: The 'result' of the operation (if applicable).
* result: The 'result' of the operation (if applicable).
* This depends on the derived operation class.
* progress: A fraction between 0.0 and 1.0 inclusive representing how far
* progress: A fraction between 0.0 and 1.0 inclusive representing how far
* along this operation is. 0.0 = indeterminate, and 1.0 is done.
* message: A progress message to display to the user.
*/
#ifndef __SEAHORSE_OPERATION_H__
#define __SEAHORSE_OPERATION_H__
#include <glib-object.h>
#include <gtk/gtk.h>
#define SEAHORSE_TYPE_OPERATION (seahorse_operation_get_type ())
#define SEAHORSE_OPERATION(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), SEAHORSE_TYPE_OPERATION, SeahorseOperation))
#define SEAHORSE_OPERATION_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), SEAHORSE_TYPE_OPERATION, SeahorseOperationClass))
#define SEAHORSE_IS_OPERATION(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SEAHORSE_TYPE_OPERATION))
#define SEAHORSE_IS_OPERATION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), SEAHORSE_TYPE_OPERATION))
#define SEAHORSE_OPERATION_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SEAHORSE_TYPE_OPERATION, SeahorseOperationClass))
struct _SeahorseOperation;
typedef struct _SeahorseOperation {
GObject parent;
......
......@@ -458,7 +458,8 @@ setup_sharing (SeahorseWidget *swidget)
/* -------------------------------------------------------------------------- */
/**
* seahorse_prefs_new
* seahorse_prefs_new:
* @parent: The #GtkWindow to set as the preferences dialog's parent
*
* Create a new preferences window.
*
......@@ -468,7 +469,10 @@ SeahorseWidget *
seahorse_prefs_new (GtkWindow *parent)
{
SeahorseWidget *swidget;
#if !(WITH_KEYSERVER && WITH_SHARING)
GtkWidget *widget = NULL;
#endif
swidget = seahorse_widget_new ("prefs", parent);
......
......@@ -18,11 +18,6 @@
* 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseSetModel: A GtkTreeModel which represents all objects
* in a SeahorseSet
*/
#ifndef __SEAHORSE_SET_MODEL_H__
#define __SEAHORSE_SET_MODEL_H__
......@@ -47,6 +42,14 @@ typedef struct _SeahorseSetModelColumn {
typedef struct _SeahorseSetModel SeahorseSetModel;
typedef struct _SeahorseSetModelClass SeahorseSetModelClass;
/**
* SeahorseSetModel:
* @parent: #GObject #SeahorseSetModel inherits from
* @set: #SeahorseSet that belongs to the model
*
* A GtkTreeModel which represents all objects in a SeahorseSet
*/
struct _SeahorseSetModel {
GObject parent;
SeahorseSet *set;
......
......@@ -19,30 +19,6 @@
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseSet: A subset list of the keys in the SeahorseContext.
*
* - Used all over by various views to narrow in on the keys that they're
* interested in.
* - Originally was going to be called SeahorseView (database parlance) but
* that's far too confusing with overloaded terminology.
* - Uses a SeahorseObjectPredicate to match keys.
* - Sends out events when keys get added and removed from it's view. Or a
* key in the view changes etc...
* - Supports per key event 'closures'. When a closure is set for a key, it's
* then passed as an argument to the 'changed' and 'removed' events.
*
* Signals:
* added: A key was added to this keyset.
* removed: A key disappeared from this keyset.
* changed: A key in the keyset changed.
* set-changed: The number of keys in the keyset changed
*
* Properties:
* count: The number of keys
* predicate: (SeahorseObjectPredicate) The predicate used for matching.
*/
#ifndef __SEAHORSE_SET_H__
#define __SEAHORSE_SET_H__
......@@ -60,7 +36,34 @@
typedef struct _SeahorseSet SeahorseSet;
typedef struct _SeahorseSetClass SeahorseSetClass;
typedef struct _SeahorseSetPrivate SeahorseSetPrivate;
/**
* SeahorseSet:
* @parent: The parent #GtkObject
*
* A subset list of the keys in the SeahorseContext.
*
* - Used all over by various views to narrow in on the keys that they're
* interested in.
* - Originally was going to be called SeahorseView (database parlance) but
* that's far too confusing with overloaded terminology.
* - Uses a SeahorseObjectPredicate to match keys.
* - Sends out events when keys get added and removed from it's view. Or a
* key in the view changes etc...
* - Supports per key event 'closures'. When a closure is set for a key, it's
* then passed as an argument to the 'changed' and 'removed' events.
*
* Signals:
* added: A key was added to this keyset.
* removed: A key disappeared from this keyset.
* changed: A key in the keyset changed.
* set-changed: The number of keys in the keyset changed
*
* Properties:
* count: The number of keys
* predicate: (SeahorseObjectPredicate) The predicate used for matching.
*/
struct _SeahorseSet {
GtkObject parent;
......
......@@ -82,11 +82,11 @@ seahorse_source_get_type (void)
/**
* seahorse_source_load
* @sksrc: A #SeahorseSource object
*
* Refreshes the #SeahorseSource's internal object listing.
*
* Returns the asynchronous refresh operation.
**/
*
* Refreshes the #SeahorseSource's internal object listing.
*
* Returns: the asynchronous refresh operation.
**/
SeahorseOperation*
seahorse_source_load (SeahorseSource *sksrc)
{
......@@ -135,7 +135,7 @@ seahorse_source_load_async (SeahorseSource *sksrc)
*
* Refreshes the #SeahorseSource's internal listing.
*
* Returns the asynchronous refresh operation.
* Returns: the asynchronous refresh operation.
**/
SeahorseOperation*
seahorse_source_search (SeahorseSource *sksrc, const gchar *match)
......
......@@ -18,19 +18,6 @@
* 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseTransferOperation: Transfer a set of keys from one key source
* to another.
*
* - Derived from SeahorseOperation
* - Exports all keys from 'from' source key source.
* - Import them into the 'to' key source.
*
* Properties:
* from-key-source: (SeahorseSource) From key source
* to-key-source: (SeahorseSource) To key source
*/
#ifndef __SEAHORSE_TRANSFER_OPERATION_H__
#define __SEAHORSE_TRANSFER_OPERATION_H__
......@@ -45,6 +32,21 @@
#define SEAHORSE_IS_TRANSFER_OPERATION_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), SEAHORSE_TYPE_TRANSFER_OPERATION))
#define SEAHORSE_TRANSFER_OPERATION_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), SEAHORSE_TYPE_TRANSFER_OPERATION, SeahorseTransferOperationClass))
/**
* SeahorseTransferOperation:
* @parent: The parent #SeahorseOperation
*
* Transfer a set of keys from one key source to another.
*
* - Derived from SeahorseOperation
* - Exports all keys from 'from' source key source.
* - Import them into the 'to' key source.
*
* Properties:
* from-key-source: (SeahorseSource) From key source
* to-key-source: (SeahorseSource) To key source
*/
DECLARE_OPERATION (Transfer, transfer)
/*< public >*/
SeahorseSource *from;
......
......@@ -18,19 +18,6 @@
* 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseUnknownSource: A source for unknown objects
*
* - Derived from SeahorseSource
* - Is used for objects that haven't been found on a key server.
*
* Properties:
* ktype: (GQuark) The ktype (ie: SKEY_UNKNOWN) of keys originating from this
key source.
* location: (SeahorseLocation) The location of objects that come from this
* source. (ie: SEAHORSE_LOCATION_MISSING)
*/
#ifndef __SEAHORSE_UNKNOWN_SOURCE_H__
#define __SEAHORSE_UNKNOWN_SOURCE_H__
......@@ -49,6 +36,23 @@ typedef struct _SeahorseUnknownSource SeahorseUnknownSource;
typedef struct _SeahorseUnknownSourceClass SeahorseUnknownSourceClass;
typedef struct _SeahorseUnknownSourcePrivate SeahorseUnknownSourcePrivate;
/**
* SeahorseUnknownSource:
* @parent: The parent #GObject
* @ktype: The #GQuark key type for the source
*
* A source for unknown objects
*
* - Derived from SeahorseSource
* - Is used for objects that haven't been found on a key server.
*
* Properties:
* ktype: (GQuark) The ktype (ie: SKEY_UNKNOWN) of keys originating from this
key source.
* location: (SeahorseLocation) The location of objects that come from this
* source. (ie: SEAHORSE_LOCATION_MISSING)
*/
struct _SeahorseUnknownSource {
GObject parent;
GQuark ktype;
......
......@@ -463,7 +463,7 @@ seahorse_util_print_fd (int fd, const char* s)
/**
* seahorse_util_printf_fd:
* @fd: The file descriptor to write to
* @fmt: The printf format of the data to write
* @data: The printf format of the data to write
* @...: The parameters to insert
*
* Returns: TRUE on success, FALSE on error
......
......@@ -19,20 +19,6 @@
* 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
/**
* SeahorseWidget: A window created from a gtkbuilder file.
*
* - All SeahorseWidget objects are destroyed when the SeahorseContext
* goes bye-bye.
* - Implements fun GtkUIManager stuff.
*
* Signals:
* destroy: The window was destroyed.
*
* Properties:
* name: (gchar*) The name of the gtkbuilder file to load.
*/
#ifndef __SEAHORSE_WIDGET_H__
#define __SEAHORSE_WIDGET_H__
......@@ -52,6 +38,25 @@
typedef struct _SeahorseWidget SeahorseWidget;
typedef struct _SeahorseWidgetClass SeahorseWidgetClass;
/**
* SeahorseWidget:
* @parent: The parent #GtkObject
* @gtkbuilder: The #GtkBuilder object for the #SeahorseWidget
* @name: The name of the gtkbuilder file
*
* A window created from a gtkbuilder file.
*
* - All SeahorseWidget objects are destroyed when the SeahorseContext
* goes bye-bye.
* - Implements fun GtkUIManager stuff.
*
* Signals:
* destroy: The window was destroyed.
*
* Properties:
* name: (gchar*) The name of the gtkbuilder file to load.
*/
struct _SeahorseWidget {
GtkObject parent;
......
......@@ -3,14 +3,15 @@
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index">
<bookinfo>
<title>libseahorse Reference Manual</title>
<releaseinfo>
for libseahorse [VERSION]
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://[SERVER]/libseahorse/index.html">http://[SERVER]/libseahorse/</ulink>.
for libseahorse-&version;
<!-- The latest version of this documentation can be found on-line at
<ulink role="online-location" url="http://[SERVER]/libseahorse/index.html">http://[SERVER]/libseahorse/</ulink>. -->
</releaseinfo>
</bookinfo>
......
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