From 00366f440d6322b2742eb1cd35835902269c0e37 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 23 Oct 2010 20:43:36 +0200 Subject: [PATCH] Some more GApplication doc tweaks --- gio/gapplication.c | 54 +++++++++++++++++++++++++------------------ gio/gapplicationcommandline.c | 18 ++++++++++++--- gio/gioenums.h | 9 ++++---- 3 files changed, 51 insertions(+), 30 deletions(-) diff --git a/gio/gapplication.c b/gio/gapplication.c index c2554c4..279d501 100644 --- a/gio/gapplication.c +++ b/gio/gapplication.c @@ -60,23 +60,22 @@ * Before using GApplication, you must choose an "application identifier". * The expected form of an application identifier is very close to that of * of a DBus bus name. - * Examples include: "com.example.MyApp" "org.example.internal-apps.Calculator" - * For convenience, the restrictions on application identifiers are reproduced - * here: - * - * Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit. - * Application identifiers must contain at least one '.' (period) character (and thus at least two elements). - * Application identifiers must not begin with a '.' (period) character. - * Application identifiers must not contain consecutive '.' (period) characters. - * Application identifiers must not exceed 255 characters. - * + * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator". + * For details on valid application identifiers, see + * g_application_id_is_valid(). * * GApplication provides convenient life cycle management by maintaining * a use count for the primary application instance. * The use count can be changed using g_application_hold() and * g_application_release(). If it drops to zero, the application exits. * - * Opening files with a GApplicationFIXME: MISSING XINCLUDE CONTENT + * Opening files with a GApplication + * + * + * FIXME: MISSING XINCLUDE CONTENT + * + * + * */ struct _GApplicationPrivate @@ -587,9 +586,20 @@ get_platform_data (GApplication *application) * @application_id: a potential application identifier * @returns: %TRUE if @application_id is valid * - * Checks if @application_id is a valid application ID. A valid ID is - * required for calls to g_application_new() and + * Checks if @application_id is a valid application identifier. + * + * A valid ID is required for calls to g_application_new() and * g_application_set_application_id(). + * + * For convenience, the restrictions on application identifiers are + * reproduced here: + * + * Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-" and must not begin with a digit. + * Application identifiers must contain at least one '.' (period) character (and thus at least two elements). + * Application identifiers must not begin with a '.' (period) character. + * Application identifiers must not contain consecutive '.' (period) characters. + * Application identifiers must not exceed 255 characters. + * **/ gboolean g_application_id_is_valid (const gchar *application_id) @@ -862,7 +872,7 @@ g_application_get_is_remote (GApplication *application) * If the application has already been registered then %TRUE is * returned with no work performed. * - * The startup() virtual function is invoked if registration succeeds + * The #GApplication::startup signal is emitted if registration succeeds * and @application is the primary instance. * * In the event of an error (such as @cancellable being cancelled, or a @@ -979,8 +989,8 @@ g_application_release (GApplication *application) * * Activates the application. * - * In essence, this results in the activate() virtual function being - * invoked in the primary instance. + * In essence, this results in the #GApplication::activate() signal being + * emitted in the primary instance. * * The application must be registered before calling this function. * @@ -1003,26 +1013,24 @@ g_application_activate (GApplication *application) /** * g_application_open: * @application: a #GApplication - * @files: an array of #GFiles to open + * @files: an array of #GFiles to open * @n_files: the length of the @files array * @hint: a hint (or ""), but never %NULL * * Opens the given files. * - * In essence, this results in the open() virtual function being invoked + * In essence, this results in the #GApplication::open signal being emitted * in the primary instance. * * @n_files must be greater than zero. * - * @hint is simply passed through to the open() virtual function. It is + * @hint is simply passed through to the ::open signal. It is * intended to be used by applications that have multiple modes for * opening files (eg: "view" vs "edit", etc). Unless you have a need * for this functionality, you should use "". * - * The application must be registered before calling this function and - * it must have the %G_APPLICATION_HANDLES_OPEN flag set. The open() - * virtual function should also be implemented in order for anything - * meaningful to happen. + * The application must be registered before calling this function + * and it must have the %G_APPLICATION_HANDLES_OPEN flag set. * * Since: 2.28 **/ diff --git a/gio/gapplicationcommandline.c b/gio/gapplicationcommandline.c index 96c1807..396bafc 100644 --- a/gio/gapplicationcommandline.c +++ b/gio/gapplicationcommandline.c @@ -53,9 +53,21 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC * of this object (ie: the process exits when the last reference is * dropped). * - * Handling commandline arguments with GApplicationFIXME: MISSING XINCLUDE CONTENT - * - * Complicated commandline handlingFIXME: MISSING XINCLUDE CONTENT + * Handling commandline arguments with GApplication + * + * + * FIXME: MISSING XINCLUDE CONTENT + * + * + * + * + * Complicated commandline handling + * + * + * FIXME: MISSING XINCLUDE CONTENT + * + * + * **/ enum diff --git a/gio/gioenums.h b/gio/gioenums.h index eba19eb..ca68183 100644 --- a/gio/gioenums.h +++ b/gio/gioenums.h @@ -1219,13 +1219,14 @@ typedef enum /** * GApplicationFlags: * @G_APPLICATION_FLAGS_NONE: Default - * @G_APPLICATION_IS_SERVICE: Stay around for a while when the use count - * falls to zero. + * @G_APPLICATION_IS_SERVICE: Run as a service. In this mode, registration + * fails if the service is already running, and the application will + * stay around for a while when the use count falls to zero. * @G_APPLICATION_IS_LAUNCHER: Don't try to become the primary instance. * @G_APPLICATION_HANDLES_OPEN: This application handles opening files (in the * primary instance) - * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command lines - * (in the primary instance) + * @G_APPLICATION_HANDLES_COMMAND_LINE: This application handles command line + * arguments (in the primary instance) * * Flags used to define the behaviour of a #GApplication. * -- 2.7.4