Various doc tweaks

This commit is contained in:
Matthias Clasen 2010-11-28 23:55:43 -05:00
parent 1f044a503a
commit eed36d38d1
21 changed files with 91 additions and 67 deletions

View File

@ -32,6 +32,10 @@
<title>File System Monitoring</title>
<xi:include href="xml/gfilemonitor.xml"/>
</chapter>
<chapter id="utils">
<title>File-related Utilities</title>
<xi:include href="xml/gfilenamecompleter.xml"/>
</chapter>
<chapter id="async">
<title>Asynchronous I/O</title>
<xi:include href="xml/gcancellable.xml"/>
@ -161,10 +165,6 @@
<xi:include href="xml/gdbusnamewatching.xml"/>
<xi:include href="xml/gdbusproxy.xml"/>
</chapter>
<chapter id="utils">
<title>Utilities</title>
<xi:include href="xml/gfilenamecompleter.xml"/>
</chapter>
<chapter id="settings">
<title>Settings</title>
<xi:include href="xml/gsettings.xml"/>

View File

@ -3010,7 +3010,7 @@ GTlsCertificateFlags
<SECTION>
<FILE>gtlsbackend</FILE>
<TITLE>GTlsBackend</FILE>
<TITLE>GTlsBackend</TITLE>
G_TLS_BACKEND_EXTENSION_POINT_NAME
GTlsBackend
GTlsBackendInterface
@ -3033,7 +3033,6 @@ g_tls_backend_get_type
<FILE>gtlscertificate</FILE>
<TITLE>GTlsCertificate</TITLE>
GTlsCertificate
g_tls_certificate_new
g_tls_certificate_new_from_pem
g_tls_certificate_new_from_file
g_tls_certificate_new_from_files

View File

@ -28,7 +28,7 @@ G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
/**
* SECTION:gaction
* @title: GAction
* @short_description: an action
* @short_description: An action
*
* #GAction represents a single named action.
*

View File

@ -28,7 +28,7 @@
/**
* SECTION:gactiongroup
* @title: GActionGroup
* @short_description: a group of actions
* @short_description: A group of actions
*
* #GActionGroup represents a group of actions.
*

View File

@ -33,8 +33,7 @@ G_DEFINE_TYPE (GApplicationCommandLine, g_application_command_line, G_TYPE_OBJEC
/**
* SECTION:gapplicationcommandline
* @title: GApplicationCommandLine
* @short_description: A class representing a command-line invocation of
* an application
* @short_description: A command-line invocation of an application
* @see_also: #GApplication
*
* #GApplicationCommandLine represents a command-line invocation of

View File

@ -48,6 +48,7 @@
/**
* SECTION:gdesktopappinfo
* @title: GDesktopAppInfo
* @short_description: Application information from desktop files
* @include: gio/gdesktopappinfo.h
*

View File

@ -34,7 +34,7 @@
* of times per second and is capable of being put into synch with an
* external time source.
*
* A number of #GPeriodicTickFunc<!-- -->s are registered with
* A number of #GPeriodicTickFuncs are registered with
* g_periodic_add() and are called each time the clock "ticks".
*
* The tick functions can report "damage" (ie: updates that need to be
@ -262,7 +262,7 @@ g_periodic_prepare (GSource *source,
/* We need to run. */
{
gint64 remaining;
remaining = periodic->priv->last_run + 1000000 * (1 + periodic->priv->skip_frames) -
g_periodic_get_microticks (periodic);
@ -354,8 +354,10 @@ g_periodic_dispatch (GSource *source,
}
static void
g_periodic_get_property (GObject *object, guint prop_id,
GValue *value, GParamSpec *pspec)
g_periodic_get_property (GObject *object,
guint prop_id,
GValue *value,
GParamSpec *pspec)
{
GPeriodic *periodic = G_PERIODIC (object);
@ -379,8 +381,10 @@ g_periodic_get_property (GObject *object, guint prop_id,
}
static void
g_periodic_set_property (GObject *object, guint prop_id,
const GValue *value, GParamSpec *pspec)
g_periodic_set_property (GObject *object,
guint prop_id,
const GValue *value,
GParamSpec *pspec)
{
GPeriodic *periodic = G_PERIODIC (object);
@ -445,11 +449,25 @@ g_periodic_class_init (GPeriodicClass *class)
object_class->set_property = g_periodic_set_property;
object_class->finalize = g_periodic_finalize;
/**
* GPeriodic::tick
* @periodic: the #GPeriodic on which the signal was emitted
* @timestamp: the timestamp at the time of the tick
*
* The ::tick signal gets emitted whenever the clock "fires".
*/
g_periodic_tick = g_signal_new ("tick", G_TYPE_PERIODIC,
G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET(GPeriodicClass, tick),
NULL, NULL, _gio_marshal_VOID__INT64,
G_TYPE_NONE, 1, G_TYPE_INT64);
/**
* GPeriodic::repair:
* @periodic: the #GPeriodic on which the signal was emitted
*
* The ::repair signal gets emitted to start the "repair" phase.
*/
g_periodic_repair = g_signal_new ("repair", G_TYPE_PERIODIC,
G_SIGNAL_RUN_LAST,
G_STRUCT_OFFSET (GPeriodicClass, repair),
@ -484,13 +502,14 @@ g_periodic_class_init (GPeriodicClass *class)
* Temporarily blocks @periodic from running in order to bring it in
* synch with an external time source.
*
* This function must be called from a handler of the "repair" signal.
* This function must be called from a handler of the #GPeriodic::repair
* signal.
*
* If this function is called, emission of the tick signal will be
* suspended until g_periodic_unblock() is called an equal number of
* times. Once that happens, the "tick" signal will run immediately and
* future "tick" signals will be emitted relative to the time at which
* the last call to g_periodic_unblock() occured.
* If this function is called, emission of the #GPeriodic::tick signal
* will be suspended until g_periodic_unblock() is called an equal number
* of times. Once that happens, the ::tick signal will run immediately
* and future ::tick signals will be emitted relative to the time at
* which the last call to g_periodic_unblock() occured.
*
* Since: 2.28
**/
@ -510,9 +529,9 @@ g_periodic_block (GPeriodic *periodic)
*
* Reverses the effect of a previous call to g_periodic_block().
*
* If this call removes the last block, the tick signal is immediately
* run. The repair signal may also be run if the clock is marked as
* damaged.
* If this call removes the last block, the ::tick signal is
* immediately run. The ::repair signal may also be run if the clock
* is marked as damaged.
*
* @unblock_time is the monotonic time, as per g_get_monotonic_time(),
* at which the event causing the unblock occured.
@ -545,20 +564,21 @@ g_periodic_unblock (GPeriodic *periodic,
* @user_data: data for @callback
* @notify: for freeing @user_data when it is no longer needed
*
* Request periodic calls to @callback to start. The periodicity of the
* calls is determined by the 'hz' property.
* Request periodic calls to @callback to start. The periodicity of
* the calls is determined by the #GPeriodic:hz property.
*
* This function may not be called from a handler of the repair signal,
* but it is perfectly reasonable to call it from a handler of the tick
* signal.
* This function may not be called from a handler of the ::repair
* signal, but it is perfectly reasonable to call it from a handler
* of the ::tick signal.
*
* The callback may be cancelled later by using g_periodic_remove() on
* the return value of this function.
* The callback may be cancelled later by using g_periodic_remove()
* on the return value of this function.
*
* Returns: a non-zero tag identifying this callback
*
* Since: 2.28
**/
/**
* GPeriodicTickFunc:
* @periodic: the #GPeriodic clock that is ticking
@ -568,8 +588,8 @@ g_periodic_unblock (GPeriodic *periodic,
* The signature of the callback function that is called when the
* #GPeriodic clock ticks.
*
* The @timestamp parameter is equal for all callbacks called during a
* particular tick on a given clock.
* The @timestamp parameter is equal for all callbacks called during
* a particular tick on a given clock.
*
* Since: 2.28
**/
@ -605,9 +625,9 @@ g_periodic_add (GPeriodic *periodic,
*
* @tag is the ID returned by that function.
*
* This function may not be called from a handler of the repair signal,
* but it is perfectly reasonable to call it from a handler of the tick
* signal.
* This function may not be called from a handler of the ::repair
* signal, but it is perfectly reasonable to call it from a handler
* of the ::tick signal.
*
* Since: 2.28
**/
@ -626,7 +646,7 @@ g_periodic_remove (GPeriodic *periodic,
if (tick->id == tag)
{
/* do this first incase the destroy notify re-enters */
/* do this first, in case the destroy notify re-enters */
*iter = g_slist_remove (*iter, tick);
if (tick->notify)
@ -644,8 +664,8 @@ g_periodic_remove (GPeriodic *periodic,
* g_periodic_damaged:
* @periodic: a #GPeriodic clock
*
* Report damage and schedule the "repair" signal to be emitted during
* the next repair phase.
* Report damage and schedule the ::repair signal to be emitted
* during the next repair phase.
*
* You may not call this function during the repair phase.
*
@ -666,7 +686,7 @@ g_periodic_damaged (GPeriodic *periodic)
*
* Gets the frequency of the clock.
*
* Returns: the frquency of the clock, in Hz
* Returns: the frequency of the clock, in Hz
*
* Since: 2.28
**/
@ -713,13 +733,14 @@ g_periodic_get_low_priority (GPeriodic *periodic)
/**
* g_periodic_new:
* @hz: the frequency of the new clock in Hz (between 1 and 120)
* @priority: the #GSource priority to run at
* @high_priority: the #GSource priority to run at
* @low_priority: ignore tasks below this priority
*
* Creates a new #GPeriodic clock.
*
* The created clock is attached to the thread-default main context in
* effect at the time of the call to this function. See
* g_main_context_push_thread_default() for more information.
* The created clock is attached to the thread-default main context
* in effect at the time of the call to this function.
* See g_main_context_push_thread_default() for more information.
*
* Due to the fact that #GMainContext is only accurate to the nearest
* millisecond, the frequency can not meaningfully get too close to

View File

@ -28,7 +28,7 @@
/**
* SECTION:gpermission
* @title: GPermission
* @short_description: an object representing the permission to perform
* @short_description: An object representing the permission to perform
* a certain action
*
* A #GPermission represents the status of the caller's permission to

View File

@ -35,8 +35,8 @@
*
* #GPollableInputStream is implemented by #GInputStream<!-- -->s that
* can be polled for readiness to read. This can be used when
* interfacing with a non-gio API that expects
* unix-file-descriptor-style asynchronous I/O rather than gio-style.
* interfacing with a non-GIO API that expects
* UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
*
* Since: 2.28
*/
@ -125,9 +125,8 @@ g_pollable_input_stream_is_readable (GPollableInputStream *stream)
*
* As with g_pollable_input_stream_is_readable(), it is possible that
* the stream may not actually be readable even after the source
* triggers, so you should use
* g_pollable_input_stream_read_nonblocking() rather than
* g_input_stream_read() from the callback.
* triggers, so you should use g_pollable_input_stream_read_nonblocking()
* rather than g_input_stream_read() from the callback.
*
* Returns: a new #GSource
*

View File

@ -92,7 +92,7 @@ gssize g_pollable_input_stream_read_nonblocking (GPollableInputStream *stream
GError **error);
/* Helper method for stream implementations */
GSource *g_pollable_source_new (GObject *stream);
GSource *g_pollable_source_new (GObject *pollable_stream);
G_END_DECLS

View File

@ -36,8 +36,8 @@
*
* #GPollableOutputStream is implemented by #GOutputStream<!-- -->s that
* can be polled for readiness to write. This can be used when
* interfacing with a non-gio API that expects
* unix-file-descriptor-style asynchronous I/O rather than gio-style.
* interfacing with a non-GIO API that expects
* UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.
*
* Since: 2.28
*/
@ -126,9 +126,8 @@ g_pollable_output_stream_is_writable (GPollableOutputStream *stream)
*
* As with g_pollable_output_stream_is_writable(), it is possible that
* the stream may not actually be writable even after the source
* triggers, so you should use
* g_pollable_output_stream_write_nonblocking() rather than
* g_output_stream_write() from the callback.
* triggers, so you should use g_pollable_output_stream_write_nonblocking()
* rather than g_output_stream_write() from the callback.
*
* Returns: a new #GSource
*

View File

@ -42,7 +42,7 @@
/**
* SECTION:gsettings
* @short_description: a high-level API for application settings
* @short_description: High-level API for application settings
*
* The #GSettings class provides a convenient API for storing and retrieving
* application settings.

View File

@ -49,7 +49,7 @@ struct _GSettingsBackendPrivate
/**
* SECTION:gsettingsbackend
* @title: GSettingsBackend
* @short_description: an interface for settings backend implementations
* @short_description: Interface for settings backend implementations
* @include: gio/gsettingsbackend.h
* @see_also: #GSettings, #GIOExtensionPoint
*

View File

@ -33,7 +33,7 @@ G_DEFINE_TYPE_WITH_CODE (GSimpleAction, g_simple_action, G_TYPE_OBJECT,
/**
* SECTION:gsimpleaction
* @title: GSimpleAction
* @short_description: a simple GSimpleAction
* @short_description: A simple GSimpleAction
*
* A #GSimpleAction is the obvious simple implementation of the #GSimpleAction
* interface. This is the easiest way to create an action for purposes of

View File

@ -25,7 +25,7 @@
/**
* SECTION:gsimpleactiongroup
* @title: GSimpleActionGroup
* @short_description: a simple GActionGroup implementation
* @short_description: A simple GActionGroup implementation
*
* #GSimpleActionGroup is a hash table filled with #GAction objects,
* implementing the #GActionGroup interface.

View File

@ -28,7 +28,7 @@
/**
* SECTION:gsimplepermission
* @title: GSimplePermission
* @short_description: a GPermission that doesn't change value
* @short_description: A GPermission that doesn't change value
*
* #GSimplePermission is a trivial implementation of #GPermission that
* represents a permission that is either always or never allowed. The

View File

@ -13,7 +13,7 @@
/**
* SECTION: gtcpconnection
* @title: GTcpConnection
* @short_description: a TCP GSocketConnection
* @short_description: A TCP GSocketConnection
* @see_also: #GSocketConnection.
*
* This is the subclass of #GSocketConnection that is created

View File

@ -23,8 +23,7 @@
/**
* SECTION: gtcpwrapperconnection
* @title: GTcpWrapperConnection
* @short_description: a wrapper for non-#GSocketConnection-based
* #GIOStream<!-- -->s that are nonetheless based on a #GSocket
* @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams
* @see_also: #GSocketConnection.
*
* A #GTcpWrapperConnection can be used to wrap a #GIOStream that is

View File

@ -29,7 +29,7 @@
/**
* SECTION:gtls
* @title: TLS Overview
* @short_description: TLS (aka SSL) support for #GSocketConnection
* @short_description: TLS (aka SSL) support for GSocketConnection
* @include: gio/gio.h
*
* #GTlsConnection and related classes provide TLS (Transport Layer

View File

@ -31,7 +31,7 @@
/**
* SECTION: gtlscertificate
* @title: GTlsCertificate
* @short_description: a TLS certificate
* @short_description: TLS certificate
* @see_also: #GTlsConnection
*
* A certificate used for TLS authentication and encryption.

View File

@ -666,6 +666,8 @@ g_tls_connection_certificate_accumulator (GSignalInvocationHint *ihint,
* Used by #GTlsConnection implementations to emit the
* #GTlsConnection::need-certificate signal.
*
* Returns: a new #GTlsCertificate
*
* Since: 2.28
*/
GTlsCertificate *
@ -681,10 +683,15 @@ g_tls_connection_emit_need_certificate (GTlsConnection *conn)
/**
* g_tls_connection_emit_accept_certificate:
* @conn: a #GTlsConnection
* @peer_cert: the peer's #GTlsCertificate
* @errors: the problems with @peer_cert
*
* Used by #GTlsConnection implementations to emit the
* #GTlsConnection::accept-certificate signal.
*
* Return value: %TRUE if one of the signal handlers has returned
* %TRUE to accept @peer_cert
*
* Since: 2.28
*/
gboolean