Commit 41d1650c authored by Alexander Larsson's avatar Alexander Larsson Committed by Alexander Larsson

Fix up a bunch of details in the docs.

2007-12-12  Alexander Larsson  <alexl@redhat.com>

        * gappinfo.[ch]:
        * gasyncresult.c:
        * gbufferedinputstream.c:
        * gbufferedoutputstream.c:
        * gcancellable.c:
        * gcontenttype.c:
        * gdatainputstream.[ch]:
        * gdesktopappinfo.c:
        * gdirectorymonitor.c:
        * gfile.[ch]:
        * gfileattribute.[ch]:
        * gfileicon.[ch]:
        * gfileinfo.h:
        * gfileinputstream.h:
        * gfilemonitor.[ch]:
        * gfileoutputstream.[ch]:
        * gfilterinputstream.h:
        * gfilteroutputstream.h:
        * gicon.h:
        * gioscheduler.c:
        * gloadableicon.[ch]:
        * gmemoryinputstream.c:
        * gmountoperation.c:
        * gthemedicon.c:
	Fix up a bunch of details in the docs.

        * glocalfileinfo.c:
	CR/LF -> LF fixups


svn path=/trunk/; revision=6100
parent 2de9f839
2007-12-12 Alexander Larsson <alexl@redhat.com>
* gappinfo.[ch]:
* gasyncresult.c:
* gbufferedinputstream.c:
* gbufferedoutputstream.c:
* gcancellable.c:
* gcontenttype.c:
* gdatainputstream.[ch]:
* gdesktopappinfo.c:
* gdirectorymonitor.c:
* gfile.[ch]:
* gfileattribute.[ch]:
* gfileicon.[ch]:
* gfileinfo.h:
* gfileinputstream.h:
* gfilemonitor.[ch]:
* gfileoutputstream.[ch]:
* gfilterinputstream.h:
* gfilteroutputstream.h:
* gicon.h:
* gioscheduler.c:
* gloadableicon.[ch]:
* gmemoryinputstream.c:
* gmountoperation.c:
* gthemedicon.c:
Fix up a bunch of details in the docs.
* glocalfileinfo.c:
CR/LF -> LF fixups
2007-12-11 David Zeuthen <davidz@redhat.com>
Rework how volumes, drives and volume monitoring is
......
......@@ -33,7 +33,7 @@
* @stability: Unstable
*
* #GAppInfo and #GAppLaunchContext are used for describing and launching
* installed system applications.
* applications installed on the system.
*
**/
......@@ -134,7 +134,10 @@ g_app_info_equal (GAppInfo *appinfo1,
* g_app_info_get_id:
* @appinfo: a #GAppInfo.
*
* Gets the ID of an application.
* Gets the ID of an application. An id is a string that
* identifies the application. The exact format of the id is
* platform dependent. For instance on Unix this is the
* desktop file id from the xdg menu specification.
*
* Returns: a string containing the application's ID.
**/
......@@ -177,7 +180,7 @@ g_app_info_get_name (GAppInfo *appinfo)
* Gets a human-readable description of an installed application.
*
* Returns: a string containing a description of the
* application @appinfo. The returned string should be not freed
* application @appinfo, or %NULL if none. The returned string should be not freed
* when no longer needed.
**/
const char *
......@@ -220,11 +223,9 @@ g_app_info_get_executable (GAppInfo *appinfo)
* @content_type: the content type.
* @error: a #GError.
*
* Sets an application as the default handler for a given type.
* Sets the application as the default handler for a given type.
*
* Returns: %TRUE if the given @appinfo is the default
* for the given @content_type. %FALSE if not,
* or in case of an error.
* Returns: %TRUE on success, %FALSE on error.
**/
gboolean
g_app_info_set_as_default_for_type (GAppInfo *appinfo,
......@@ -245,14 +246,12 @@ g_app_info_set_as_default_for_type (GAppInfo *appinfo,
/**
* g_app_info_set_as_default_for_extension:
* @appinfo: a #GAppInfo.
* @extension: a string containing the file extension.
* @extension: a string containing the file extension (without the dot).
* @error: a #GError.
*
* Sets an application as the default handler for the given file extention.
* Sets the application as the default handler for the given file extention.
*
* Returns: %TRUE if the given @appinfo is the default
* for the given @extension. %FALSE if not,
* or in case of an error.
* Returns: %TRUE on success, %FALSE on error.
**/
gboolean
g_app_info_set_as_default_for_extension (GAppInfo *appinfo,
......@@ -283,8 +282,7 @@ g_app_info_set_as_default_for_extension (GAppInfo *appinfo,
* Adds a content type to the application information to indicate the
* application is capable of opening files with the given content type.
*
* Returns: %TRUE if @appinfo supports @content_type.
* %FALSE if not, or in case of an error.
* Returns: %TRUE on success, %FALSE on error.
**/
gboolean
g_app_info_add_supports_type (GAppInfo *appinfo,
......@@ -342,8 +340,7 @@ g_app_info_can_remove_supports_type (GAppInfo *appinfo)
*
* Removes a supported type from an application, if possible.
*
* Returns: %TRUE if @content_type support was removed
* from @appinfo. %FALSE if not.
* Returns: %TRUE on success, %FALSE on error.
**/
gboolean
g_app_info_remove_supports_type (GAppInfo *appinfo,
......@@ -372,7 +369,7 @@ g_app_info_remove_supports_type (GAppInfo *appinfo,
* g_app_info_get_icon:
* @appinfo: a #GAppInfo.
*
* Gets the default icon for the application.
* Gets the icon for the application.
*
* Returns: the default #GIcon for @appinfo.
**/
......@@ -397,10 +394,17 @@ g_app_info_get_icon (GAppInfo *appinfo)
* @error: a #GError.
*
* Launches the application. Passes @files to the launched application
* as arguments, and loads the @launch_context for managing the application
* once it has been launched. On error, @error will be set accordingly.
* as arguments, using the optional @launch_context to get information
* about the details of the launcher (like what screen its is on).
* On error, @error will be set accordingly.
*
* Returns: %TRUE on successful launch, %FALSE otherwise.
* To lauch the application without arguments pass a %NULL @files list.
*
* Note that even if the launch is successful the application launched
* can fail to start if it runs into problems during startup. There is
* no way to detect this.
*
* Returns: %TRUE on successful launch, %FALSE otherwise.
**/
gboolean
g_app_info_launch (GAppInfo *appinfo,
......@@ -447,10 +451,17 @@ g_app_info_supports_uris (GAppInfo *appinfo)
* @error: a #GError.
*
* Launches the application. Passes @uris to the launched application
* as arguments, and loads the @launch_context for managing the application
* once it has been launched. On error, @error will be set accordingly.
* as arguments, using the optional @launch_context to get information
* about the details of the launcher (like what screen its is on).
* On error, @error will be set accordingly.
*
* To lauch the application without arguments pass a %NULL @uris list.
*
* Returns: %TRUE if the @appinfo was launched successfully, %FALSE otherwise.
* Note that even if the launch is successful the application launched
* can fail to start if it runs into problems during startup. There is
* no way to detect this.
*
* Returns: %TRUE on successful launch, %FALSE otherwise.
**/
gboolean
g_app_info_launch_uris (GAppInfo *appinfo,
......@@ -471,10 +482,14 @@ g_app_info_launch_uris (GAppInfo *appinfo,
/**
* g_app_info_should_show:
* @appinfo: a #GAppInfo.
* @desktop_env: a string.
* @desktop_env: A string specifying what desktop this is, or %NULL.
*
* Checks if the application info should be shown when listing
* applications available.
*
* @destkop_env is used to hide applications that are specified to
* just show up in specific desktops. For instance, passing in "GNOME"
* would show all applications specific to the Gnome desktop.
*
* Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
**/
......@@ -496,7 +511,8 @@ G_DEFINE_TYPE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT);
/**
* g_app_launch_context_new:
*
* Creates a new application launch context.
* Creates a new application launch context. This is not normally used,
* instead you instantiate a subclass of this, such as GdkLaunchContext.
*
* Returns: a #GAppLaunchContext.
**/
......@@ -546,14 +562,15 @@ g_app_launch_context_get_display (GAppLaunchContext *context,
return class->get_display (context, info, files);
}
/* should this be moved to the g_desktop_app_ implementation? */
/**
* g_app_launch_context_get_startup_notify_id:
* @context: a #GAppLaunchContext.
* @info: a #GAppInfo.
* @files: a #GList of files.
*
* Gets the DESKTOP_STARTUP_ID for the launched application, if supported.
* Initiates startup notification for the applicaiont and returns the
* DESKTOP_STARTUP_ID for the launched operation, if supported.
*
* Startup notification IDs are defined in the FreeDesktop.Org Startup
* Notifications standard, at
* <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"/>.
......@@ -583,11 +600,10 @@ g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context,
/**
* g_app_launch_context_launch_failed:
* @context: a #GAppLaunchContext.
* @startup_notify_id: a string containing the DESKTOP_STARTUP_ID
* of the launched application.
* @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id().
*
* Called when an application has failed to launch, and cancels the
* application startup notification.
* Called when an application has failed to launch, so that it can cancel
* the application startup notification started in g_app_launch_context_get_startup_notify_id().
*
**/
void
......
......@@ -43,7 +43,7 @@ G_BEGIN_DECLS
/**
* GAppInfoCreateFlags:
* @G_APP_INFO_CREATE_FLAGS_NONE: No flags.
* @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens with a terminal window.
* @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens in a terminal window.
*
* Flags used when creating a #GAppInfo.
*/
......@@ -59,7 +59,8 @@ typedef struct _GAppLaunchContextPrivate GAppLaunchContextPrivate;
/**
* GAppInfo:
*
* Information about an installed application.
* Information about an installed application and methods to launch
* it (with file arguments).
*/
typedef struct _GAppInfo GAppInfo; /* Dummy typedef */
......@@ -77,7 +78,6 @@ typedef struct _GAppInfo GAppInfo; /* Dummy typedef */
* @supports_uris: Indicates whether the application specified supports launching URIs.
* @launch_uris: Launches an application with a list of URIs.
* @should_show: Returns whether an application should be shown (e.g. when getting a list of installed applications).
* @supports_xdg_startup_notify: Indicates whether the application supports the
* <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
* <citetitle>FreeDesktop.Org Startup Notification Specification</citetitle></ulink>.
* @set_as_default_for_type: Sets an application as default for a given content type.
......@@ -115,8 +115,6 @@ struct _GAppInfoIface
GError **error);
gboolean (*should_show) (GAppInfo *appinfo,
const char *desktop_env);
gboolean (*supports_xdg_startup_notify) (GAppInfo *appinfo);
/* For changing associations */
gboolean (*set_as_default_for_type) (GAppInfo *appinfo,
......@@ -132,18 +130,6 @@ struct _GAppInfoIface
gboolean (*remove_supports_type) (GAppInfo *appinfo,
const char *content_type,
GError **error);
/*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
void (*_g_reserved3) (void);
void (*_g_reserved4) (void);
void (*_g_reserved5) (void);
void (*_g_reserved6) (void);
void (*_g_reserved7) (void);
void (*_g_reserved8) (void);
void (*_g_reserved9) (void);
void (*_g_reserved10) (void);
};
GType g_app_info_get_type (void) G_GNUC_CONST;
......@@ -193,18 +179,13 @@ GAppInfo *g_app_info_get_default_for_type (const char *content_type,
gboolean must_support_uris);
GAppInfo *g_app_info_get_default_for_uri_scheme (const char *uri_scheme);
/* TODO: missing operations:
add app as supporting a content type, but don't make it default
implement set_as_default_for_extension
can_remove, remove (as in, don't support a specific mimetype)
*/
/**
* GAppLaunchContext:
* @parent_instance: The parent instance.
*
* Gets feedback from the system when launching an application.
* Integrating the launch with the launching application. This is used to
* handle for instance startup notification and launching the new application
* on the same screen as the launching window.
*/
struct _GAppLaunchContext
{
......
......@@ -52,7 +52,8 @@
* of the operation is not needed, there is no need to call the
* "_finish()" function, GIO will take care of cleaning up the
* result and error information after the #GAsyncReadyCallback
* returns.
* returns. It is also allowed to take a reference to the #GAsyncResult and
* call "_finish()" later.
*
* Example of a typical asynchronous operation flow:
* |[
......@@ -96,9 +97,15 @@
* /<!-- -->* ... *<!-- -->/
* }
* ]|
*
* The callback for an asynchronous operation is called only once, and is
* always called, even in the case of a cancelled operation. On cancellation
* the result is a %G_IO_ERROR_CANCELLED error.
*
* Asynchronous jobs are threaded if #GThread is available, but also may
* be sent to the Main Event Loop and processed in an idle function.
* Some ascynchronous operations are implemented using synchronous call. These
* are run in a separate #GThread has been initialized, but otherwise they
* are sent to the Main Event Loop and processed in an idle function. So, if you
* truly need asynchronous operations, make sure to initialize #GThread.
**/
static void g_async_result_base_init (gpointer g_class);
......
......@@ -177,12 +177,12 @@ g_buffered_input_stream_class_init (GBufferedInputStreamClass *klass)
*
* Gets the size of the input buffer.
*
* Returns: the current buffer size, or %-1 on error.
* Returns: the current buffer size.
**/
gsize
g_buffered_input_stream_get_buffer_size (GBufferedInputStream *stream)
{
g_return_val_if_fail (G_IS_BUFFERED_INPUT_STREAM (stream), -1);
g_return_val_if_fail (G_IS_BUFFERED_INPUT_STREAM (stream), 0);
return stream->priv->len;
}
......
......@@ -248,6 +248,9 @@ g_buffered_output_stream_get_auto_grow (GBufferedOutputStream *stream)
* @auto_grow: a #gboolean.
*
* Sets whether or not the @stream's buffer should automatically grow.
* If @auto_grow is true, then each write will just make the buffer
* larger, and you must manually flush the buffer to actually write out
* the data to the underlying stream.
**/
void
g_buffered_output_stream_set_auto_grow (GBufferedOutputStream *stream,
......
......@@ -43,7 +43,8 @@
* @include: gio/gcancellable.h
*
* GCancellable is a thread-safe operation cancellation stack used
* throughout GIO to allow for cancellation of asynchronous operations.
* throughout GIO to allow for cancellation of synchronous and
* asynchronous operations.
*/
enum {
......@@ -94,6 +95,10 @@ g_cancellable_class_init (GCancellableClass *klass)
* @cancellable: a #GCancellable.
*
* Emitted when the operation has been cancelled from another thread.
*
* Can be used by implementations of cancellable operations. This will
* be emitted in the thread that tried to cancel the operation, not the
* thread the is running the operation.
*/
signals[CANCELLED] =
g_signal_new (I_("cancelled"),
......@@ -149,6 +154,13 @@ g_cancellable_init (GCancellable *cancellable)
* g_cancellable_new:
*
* Creates a new #GCancellable object.
*
* Applications that want to start one or more operations
* that should be cancellable should create a #GCancellable
* and pass it to the operations.
*
* One #GCancellable can be used in multiple consecutive
* operations, but not in multiple concurrent operations.
*
* Returns: a #GCancellable.
**/
......@@ -162,7 +174,14 @@ g_cancellable_new (void)
* g_push_current_cancellable:
* @cancellable: optional #GCancellable object, %NULL to ignore.
*
* Pushes @cancellable onto the cancellable stack.
* Pushes @cancellable onto the cancellable stack. The current
* cancllable can then be recieved using g_cancellable_get_current().
*
* This is useful when implementing cancellable operations in
* code that does not allow you to pass down the cancellable object.
*
* This is typically called automatically by e.g. #GFile operations,
* so you rarely have to call this yourself.
**/
void
g_push_current_cancellable (GCancellable *cancellable)
......@@ -180,8 +199,8 @@ g_push_current_cancellable (GCancellable *cancellable)
* g_pop_current_cancellable:
* @cancellable: optional #GCancellable object, %NULL to ignore.
*
* Pops @cancellable off the cancellable stack if @cancellable
* is on the top of the stack.
* Pops @cancellable off the cancellable stack (verifying that @cancellable
* is on the top of the stack).
**/
void
g_pop_current_cancellable (GCancellable *cancellable)
......@@ -260,7 +279,8 @@ g_cancellable_is_cancelled (GCancellable *cancellable)
* @cancellable: a #GCancellable object.
* @error: #GError to append error state to.
*
* Sets the current error to notify that the operation was cancelled.
* If the @cancelalble is cancelled, sets the error to notify
* that the operation was cancelled.
*
* Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not.
**/
......@@ -284,7 +304,9 @@ g_cancellable_set_error_if_cancelled (GCancellable *cancellable,
* g_cancellable_get_fd:
* @cancellable: a #GCancellable.
*
* Gets the file descriptor for a cancellable job.
* Gets the file descriptor for a cancellable job. This can be used to
* implement cancellable operations on Unix systems. The returned fd will
* turn readable when @cancellable is cancelled.
*
* Returns: A valid file descriptor. %-1 if the file descriptor
* is not supported, or on errors.
......@@ -314,7 +336,11 @@ g_cancellable_get_fd (GCancellable *cancellable)
* @cancellable: a #GCancellable object.
*
* Will set @cancellable to cancelled, and will emit the CANCELLED
* signal. This function is thread-safe.
* signal.
*
* This function is thread-safe. In other words, you can safely call it from
* another thread than the one running an operation that was passed
* the @cancellable.
**/
void
g_cancellable_cancel (GCancellable *cancellable)
......
......@@ -399,9 +399,11 @@ g_content_type_is_a (const char *type,
* g_content_type_is_unknown:
* @type: a content type string.
*
* Checks if the content type is known by GIO.
* Checks if the content type is the generic "unknown" type.
* On unix this is the "application/octet-stream" mimetype,
* while on win32 it is "*".
*
* Returns: %TRUE if the type is unknown.
* Returns: %TRUE if the type is the unknown type.
**/
gboolean
g_content_type_is_unknown (const char *type)
......@@ -610,9 +612,9 @@ g_content_type_get_description (const char *type)
* g_content_type_get_mime_type:
* @type: a content type string.
*
* Gets the mime-type for the content type.
* Gets the mime-type for the content type. If one is registered
*
* Returns: the registered mime-type for the given @type.
* Returns: the registered mime-type for the given @type, or NULL if unknown.
**/
char *
g_content_type_get_mime_type (const char *type)
......@@ -847,8 +849,8 @@ enumerate_mimetypes_dir (const char *dir,
/**
* g_content_types_get_registered:
*
* Gets a list of strings containing the registered content types on
* the system.
* Gets a list of strings containing all the registered content types
* known to the system.
*
* Returns: #GList of the registered content types.
**/
......
......@@ -34,7 +34,7 @@
* @see_also: #GInputStream
*
* Data input stream implements #GInputStream and includes functions for
* reading data directly from an input stream.
* reading structured data directly from a binary input stream.
*
**/
......@@ -246,8 +246,9 @@ g_data_input_stream_get_byte_order (GDataInputStream *stream)
*
* Sets the newline type for the @stream.
*
* TODO: is it valid to set this to G_DATA_STREAM_NEWLINE_TYPE_ANY, or
* should it always be set to {_LF, _CR, _CR_LF}
* Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read
* chunk ends in "CR" we must read an additional byte to know if this is "CR" or
* "CR LF", and this might block if there is no more data availible.
*
**/
void
......@@ -331,8 +332,8 @@ read_data (GDataInputStream *stream,
**/
guchar
g_data_input_stream_read_byte (GDataInputStream *stream,
GCancellable *cancellable,
GError **error)
GCancellable *cancellable,
GError **error)
{
guchar c;
......@@ -405,8 +406,8 @@ g_data_input_stream_read_int16 (GDataInputStream *stream,
**/
guint16
g_data_input_stream_read_uint16 (GDataInputStream *stream,
GCancellable *cancellable,
GError **error)
GCancellable *cancellable,
GError **error)
{
guint16 v;
......@@ -453,8 +454,8 @@ g_data_input_stream_read_uint16 (GDataInputStream *stream,
**/
gint32
g_data_input_stream_read_int32 (GDataInputStream *stream,
GCancellable *cancellable,
GError **error)
GCancellable *cancellable,
GError **error)
{
gint32 v;
......@@ -501,8 +502,8 @@ g_data_input_stream_read_int32 (GDataInputStream *stream,
**/
guint32
g_data_input_stream_read_uint32 (GDataInputStream *stream,
GCancellable *cancellable,
GError **error)
GCancellable *cancellable,
GError **error)
{
guint32 v;
......@@ -736,8 +737,8 @@ scan_for_newline (GDataInputStream *stream,
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
* Returns: a string with the line that was read in. Set @length to
* a #gsize to get the length of the read line. Returns %NULL on an error.
* Returns: a string with the line that was read in (including the newlines).
* Set @length to a #gsize to get the length of the read line. Returns %NULL on an error.
**/
char *
g_data_input_stream_read_line (GDataInputStream *stream,
......
......@@ -87,7 +87,7 @@ typedef enum {
* @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms.
* @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings.
* @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows.
* @G_DATA_STREAM_NEWLINE_TYPE_ANY: Selects any line ending type.
* @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type.
*
* #GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
**/
......
......@@ -252,9 +252,9 @@ g_desktop_app_info_new_from_filename (const char *filename)
/**
* g_desktop_app_info_new:
* @desktop_id:
* @desktop_id: the desktop file id
*
* Returns: a new #GDesktopAppInfo.
* Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
**/
GDesktopAppInfo *
g_desktop_app_info_new (const char *desktop_id)
......@@ -375,8 +375,11 @@ g_desktop_app_info_get_name (GAppInfo *appinfo)
/**
* g_desktop_app_info_get_is_hidden:
* @info:
*
* @info: a #GDesktopAppInfo.
*
* A desktop file is hidden if the Hidden key in it is
* set to True.
*
* Returns: %TRUE if hidden, %FALSE otherwise.
**/
gboolean
......@@ -909,14 +912,6 @@ g_desktop_app_info_supports_uris (GAppInfo *appinfo)
(strstr (info->exec, "%U") != NULL);
}
static gboolean
g_desktop_app_info_supports_xdg_startup_notify (GAppInfo *appinfo)
{
GDesktopAppInfo *info = G_DESKTOP_APP_INFO (appinfo);
return info->startup_notify;
}
static gboolean
g_desktop_app_info_launch_uris (GAppInfo *appinfo,
GList *uris,
......@@ -1462,7 +1457,6 @@ g_desktop_app_info_iface_init (GAppInfoIface *iface)
iface->get_icon = g_desktop_app_info_get_icon;
iface->launch = g_desktop_app_info_launch;
iface->supports_uris = g_desktop_app_info_supports_uris;
iface->supports_xdg_startup_notify = g_desktop_app_info_supports_xdg_startup_notify;
iface->launch_uris = g_desktop_app_info_launch_uris;
iface->should_show = g_desktop_app_info_should_show;
iface->set_as_default_for_type = g_desktop_app_info_set_as_default_for_type;
......
......@@ -36,7 +36,7 @@
* @short_description: Directory Monitor
* @see_also: #GFileMonitor
*
* Monitors a directory for changes.
* Monitors a directory for changes to files in it.
*
**/
......@@ -236,7 +236,10 @@ g_directory_monitor_init (GDirectoryMonitor *monitor)
* g_directory_monitor_cancel:
* @monitor: a #GDirectoryMonitor.
*
* Cancels the monitoring activity on @monitor.
* Cancels the monitoring activity on @monitor. Note that
* the monitor is automatically cancelled when finalized.
*
* It is safe to call this multiple times.
*
* Returns: %TRUE if the monitor was cancelled successfully. %FALSE otherwise.
**/
......@@ -260,11 +263,9 @@ g_directory_monitor_cancel (GDirectoryMonitor *monitor)
/**
* g_directory_monitor_set_rate_limit:
* @monitor: a #GDirectoryMonitor.
* @limit_msecs: an integer to set the limit of the directory monitor
* in milliseconds.
* @limit_msecs: the change rate limit of the directory monitor in milliseconds.
*
* Sets the limit of the directory monitor to watch for changes every
* @limit_msecs milliseconds.
* Report same consecutive changes of the same type at most once each @limit_msecs milliseconds.
**/
void
g_directory_monitor_set_rate_limit (GDirectoryMonitor *monitor,
......
This diff is collapsed.
......@@ -44,6 +44,7 @@ G_BEGIN_DECLS
* Flags used when querying a #GFileInfo.
*/
typedef enum {
G_FILE_QUERY_INFO_FLAGS_NONE = 0,
G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (1<<0) /*< nick=nofollow-symlinks >*/
} GFileQueryInfoFlags;
......@@ -64,9 +65,9 @@ typedef enum {
* GFileCopyFlags:
* @G_FILE_COPY_FLAGS_NONE: No flags set.
* @G_FILE_COPY_OVERWRITE: Overwrite any existing files
* @G_FILE_COPY_BACKUP: Make a backup of any existing files. TODO: explain backup naming scheme.
* @G_FILE_COPY_BACKUP: Make a backup of any existing files.
* @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks.
* @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set (see #GFileInfo).
* @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo).
* @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported.
*
* Flags used when copying or moving files.
......
......@@ -39,8 +39,8 @@
*
* Keys are strings that contain a key namespace and a key name, separated
* by a colon, e.g. "namespace:keyname". Namespaces are included to sort
* key-value pairs by namespaces for relevance. Keys can be searched
* for using wildcards, e.g. "std:*" will return all of the keys in the
* key-value pairs by namespaces for relevance. Keys can be retrived
* using wildcards, e.g. "std:*" will return all of the keys in the
* "std" namespace.
*
* Values are stored within the list in #GFileAttributeValue structures.
......@@ -48,16 +48,14 @@
* Upon creation of a #GFileAttributeValue, the type will be set to
* %G_FILE_ATTRIBUTE_TYPE_INVALID.
*
* The Key-value list is stored within the #GFile structure as a
* #GFileAttributeInfoList. This list is queryable by key names
* The list of possible attributes for a filesystem (pointed to by a #GFile) is
* availible as a #GFileAttributeInfoList. This list is queryable by key names
* as indicated earlier.
*
* Classes that implement #GFileIface will create a #GFileAttributeInfoList and
* install default keys and values for their given file system, architecture,
* and other possible implementation details (e.g., on a UNIX system, a file
* attribute key will be registered for the user id for a given file). Other
* attributes can be appended to a #GFileAttributeList later by
* g_file_attribute_info_list_add().
* attribute key will be registered for the user id for a given file).
*
* <para>
* <table>
......@@ -83,7 +81,7 @@
* NTFS ACLs in Windows should be mapped to these values.</entry></row>
* <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes
* simple boolean keys for checking if a file or path supports mount operations, e.g.
* mount, unmount, eject.</entry></row>
* mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row>
* <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
* access, changed, created times. </entry></row>
* <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
......@@ -95,11 +93,12 @@
* for checking if a file is marked as an archive file.</entry></row>
* <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information
* about who owns a file. May not be available for all file systems. Examples include
* "user" for getting the user name of the file owner.</entry></row>
* "user" for getting the user name of the file owner. This information is often mapped from
* some backend specific data such as a unix UID.</entry></row>
* <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes
* information about file thumbnails and their location within the file system. Exaples of
* keys in this namespace include "path" to get the location of a thumbnail, and "failed"
* to check if thumbnailing failed.</entry></row>
* to check if thumbnailing of the file failed.</entry></row>
* <row><entry>"fs"</entry><entry>The "Filesystem" namespace. Gets information
* about the file system where a file is located, such as its type, how much
* space is left available, and the overall size of the file system.</entry></row>
......
......@@ -30,7 +30,7 @@ G_BEGIN_DECLS
/**
* GFileAttributeType:
* @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type.
* @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated C string.
* @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string.
* @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes.
* @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value.
* @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer.
......@@ -59,7 +59,7 @@ typedef enum {
* @G_FILE_ATTRIBUTE_FLAGS_COPY_WITH_FILE: copy the attribute values when the file is copied.
* @G_FILE_ATTRIBUTE_FLAGS_COPY_WHEN_MOVED: copy the attribute values when the file is moved.
*
* Indicates how to transfer file attributes to new #GFile structures when they are copied.
* A flag specifying the behaviour of an attribute.
**/
typedef enum {
G_FILE_ATTRIBUTE_FLAGS_NONE = 0,
......@@ -107,11 +107,11 @@ typedef struct {
/**
* GFileAttributeInfo:
* @name: a string containing the key's name.
* @type: a #GFileAttributeType for the key.
* @name: the name of the attribute.
* @type: the #GFileAttributeType type of the attribute.
* @flags: a set of #GFileAttributeFlags.
*
* A Key-Value pair definition.
* Information about a specific attribute.
**/
typedef struct {
char *name;
......
......@@ -29,11 +29,12 @@
/**
* SECTION:gfileicon
* @short_description: Icons for given files
* @short_description: Icons pointing to an image file
* @see_also: #GIcon, #GLoadableIcon
* @include: gio/gfileicon.h
*
* #GFileIcon gets the default icon for a #GFile.
* #GFileIcon specifies an icon by pointing to an image file
* to be used as icon.
*
**/
......
......@@ -38,7 +38,7 @@ G_BEGIN_DECLS
/**
* GFileIcon: