[PATCH] more documentation updates



somehow the documentation regarding the Xfer operations didn't get in
yesterday, this is a patch to fix this and some warnings during the
building of the documentation.


-- 
Diego González <diego pemas net>
Index: gnome-vfs/libgnomevfs/gnome-vfs-xfer.h
===================================================================
RCS file: /cvs/gnome/gnome-vfs/libgnomevfs/gnome-vfs-xfer.h,v
retrieving revision 1.12
diff -u -r1.12 gnome-vfs-xfer.h
--- gnome-vfs/libgnomevfs/gnome-vfs-xfer.h	29 Oct 2002 10:37:22 -0000	1.12
+++ gnome-vfs/libgnomevfs/gnome-vfs-xfer.h	19 Dec 2002 15:41:36 -0000
@@ -32,6 +32,35 @@
  * FIXME bugzilla.eazel.com 1205:
  * Split these up into xfer options and xfer actions
  */
+
+/**
+ * GnomeVFSXferOptions:
+ * @GNOME_VFS_XFER_DEFAULT: Default behavior. Which is to do a straight one
+ * to one copy.
+ * @GNOME_VFS_XFER_UNUSED_1:
+ * @GNOME_VFS_XFER_FOLLOW_LINKS: This means follow the value of the symbolic
+ * link when copying. (ie treat a symbolic link as a directory)
+ * @GNOME_VFS_XFER_UNUSED_2:
+ * @GNOME_VFS_XFER_RECURSIVE: Do a recursive copy of the source to the
+ * destination. Equivalent to the cp -r option in GNU cp.
+ * @GNOME_VFS_XFER_SAMEFS: Allow copying onto the same filesystem.
+ * @GNOME_VFS_XFER_DELETE_ITEMS: Equivalent to a mv.Where you will copy
+ * the contents of the source to the destination and then remove data from
+ * the source URI.
+ * @GNOME_VFS_XFER_EMPTY_DIRECTORIES:
+ * @GNOME_VFS_XFER_NEW_UNIQUE_DIRECTORY: Cill create a directory if it doesn't
+ * exist in the destination area. Useful with the GNOME_VFS_XFER_RECURSIVE xfer
+ * option.
+ * @GNOME_VFS_XFER_REMOVESOURCE: Remove the source data after whatever xfer
+ * option has been taken.
+ * @GNOME_VFS_XFER_USE_UNIQUE_NAMES: Check to make sure that what you copy onto
+ * the destination is not overwritten. It will only copy the unique items from
+ * the source to the destination.
+ * @GNOME_VFS_XFER_LINK_ITEMS:
+ * @GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE:
+ *
+ * Describes the set of options that a transfer can deal with.
+ **/
 typedef enum {
 	GNOME_VFS_XFER_DEFAULT = 0,
 	GNOME_VFS_XFER_UNUSED_1 = 1 << 0,
@@ -45,29 +74,42 @@
 	GNOME_VFS_XFER_REMOVESOURCE = 1 << 8,
 	GNOME_VFS_XFER_USE_UNIQUE_NAMES = 1 << 9,
 	GNOME_VFS_XFER_LINK_ITEMS = 1 << 10,
-	GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE = 1 << 11,
+	GNOME_VFS_XFER_FOLLOW_LINKS_RECURSIVE = 1 << 11
 } GnomeVFSXferOptions;
 
-/* Progress status, to be reported to the caller of the transfer operation.  */
+/**
+ * GnomeVFSXferProgressStatus:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_OK:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE:
+ * @GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE: During the duplicate status the
+ * progress callback is asked to supply a new unique name.
+ *
+ * Progress status, to be reported to the caller of the transfer operation.
+ **/
 typedef enum {
 	GNOME_VFS_XFER_PROGRESS_STATUS_OK = 0,
 	GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR = 1,
 	GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE = 2,
-	/* during the duplicate status the progress callback is asked to
-	   supply a new unique name */
 	GNOME_VFS_XFER_PROGRESS_STATUS_DUPLICATE = 3
 } GnomeVFSXferProgressStatus;
 
-/* The different ways to deal with overwriting during a transfer operation.  */
+/**
+ * GnomeVFSXferOverwriteMode:
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_ABORT: Aborts the transfer with and error
+ * (GNOME_VFS_ERROR_FILEEXISTS).
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_QUERY: Invoke the progress callback with
+ * a GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE status code.
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE: Replace the files silently.
+ * @GNOME_VFS_XFER_OVERWRITE_MODE_SKIP: Skip duplicate files silenty.
+ *
+ * The different ways to deal with overwriting during a transfer operation.
+**/
+          
 typedef enum {
-	/* Interrupt transferring with an error (GNOME_VFS_ERROR_FILEEXISTS).  */
 	GNOME_VFS_XFER_OVERWRITE_MODE_ABORT = 0,
-	/* Invoke the progress callback with a
-	   `GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE' status code. */
 	GNOME_VFS_XFER_OVERWRITE_MODE_QUERY = 1,
-	/* Overwrite files silently.  */
 	GNOME_VFS_XFER_OVERWRITE_MODE_REPLACE = 2,
-	/* Ignore files silently.  */
 	GNOME_VFS_XFER_OVERWRITE_MODE_SKIP = 3
 } GnomeVFSXferOverwriteMode;
 
@@ -89,26 +131,35 @@
 	GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE = 1,
 	GNOME_VFS_XFER_OVERWRITE_ACTION_REPLACE_ALL = 2,
 	GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP = 3,
-	GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL = 4,
+	GNOME_VFS_XFER_OVERWRITE_ACTION_SKIP_ALL = 4
 } GnomeVFSXferOverwriteAction;
 
+/**
+ * GnomeVFSXferErrorMode:
+ * @GNOME_VFS_XFER_ERROR_MODE_ABORT: The operation will be aborted whenever the
+ * transfer is interrupted. The error code returned is the code of the operation
+ * that caused the error.
+ * @GNOME_VFS_XFER_ERROR_MODE_QUERY: No error occured. Invoke the progress
+ * callback with a #GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR status code.
+ *
+ **/
 typedef enum {
-	/* Interrupt transferring with an error (code returned is code of the
-           operation that has caused the error).  */
 	GNOME_VFS_XFER_ERROR_MODE_ABORT = 0,
-	/* Invoke the progress callback with a
-	   `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR' status code. */
-	GNOME_VFS_XFER_ERROR_MODE_QUERY = 1,
+	GNOME_VFS_XFER_ERROR_MODE_QUERY = 1
 } GnomeVFSXferErrorMode;
 
-/* This defines the possible actions to be performed after an error has
-   occurred.  */
+/**
+ * GnomeVFSXferErrorAction:
+ * @GNOME_VFS_XFER_ERROR_ACTION_ABORT: Interrupt operation and return 
+ * #GNOME_VFS_ERROR_INTERRUPTED.
+ * @GNOME_VFS_XFER_ERROR_ACTION_RETRY: Try the same operation again.
+ * @GNOME_VFS_XFER_ERROR_ACTION_SKIP: Skip this file and continue normally.
+ *
+ * Defines the possible actions to be performed after an error has occurred.
+ **/
 typedef enum {
-	/* Interrupt operation and return `GNOME_VFS_ERROR_INTERRUPTED'.  */
 	GNOME_VFS_XFER_ERROR_ACTION_ABORT = 0,
-	/* Try the same operation again.  */
 	GNOME_VFS_XFER_ERROR_ACTION_RETRY = 1,
-	/* Skip this file and continue normally.  */
 	GNOME_VFS_XFER_ERROR_ACTION_SKIP = 2
 } GnomeVFSXferErrorAction;
 
@@ -116,46 +167,60 @@
    comments are marked with `(*)' are always reported in "normal" (i.e. no
    error) condition; the other ones are only reported if an error happens in
    that specific phase.  */
+
+/**
+ * GnomeVFSXferPhase:
+ * @GNOME_VFS_XFER_PHASE_INITIAL: Initial phase.
+ * @GNOME_VFS_XFER_CHECKING_DESTINATION: Checking if destination can handle move/copy.
+ * @GNOME_VFS_XFER_PHASE_COLLECTING: Collecting file list.
+ * @GNOME_VFS_XFER_PHASE_READYTOGO: File list collected (*).
+ * @GNOME_VFS_XFER_PHASE_OPENSOURCE: Opening source file for reading.
+ * @GNOME_VFS_XFER_PHASE_OPENTARGET: Creating target file for copy.
+ * @GNOME_VFS_XFER_PHASE_COPYING: Copying data from source to target (*).
+ * @GNOME_VFS_XFER_PHASE_MOVING: Moving file from source to target (*).
+ * @GNOME_VFS_XFER_PHASE_READSOURCE: Reading data from source file.
+ * @GNOME_VFS_XFER_PHASE_WRITETARGET: Writing data to target file.
+ * @GNOME_VFS_XFER_PHASE_CLOSESOURCE: Closing source file.
+ * @GNOME_VFS_XFER_PHASE_CLOSETARGET: Closing target file.
+ * @GNOME_VFS_XFER_PHASE_DELETESOURCE: Deleting source file.
+ * @GNOME_VFS_XFER_PHASE_SETATTRIBUTES: Setting attributes on target file.
+ * @GNOME_VFS_XFER_PHASE_FILECOMPLETED: Go to the next file (*).
+ * @GNOME_VFS_XFER_PHASE_CLEANUP: Cleaning up after a move (removing source files, etc.).
+ * @GNOME_VFS_XFER_PHASE_COMPLETED: Operation finished (*).
+ * @GNOME_VFS_XFER_NUM_PHASES:
+ *
+ * This specifies the current phase in the transfer operation. Phases whose
+ * comment sare marked with (*) are always reported in "normal" (i.e. no error)
+ * condition; theother ones are only reported if an error happens in that
+ * specific phase.
+ **/
 typedef enum {
-	/* Initial phase */
 	GNOME_VFS_XFER_PHASE_INITIAL,
-	/* Checking if destination can handle move/copy */
 	GNOME_VFS_XFER_CHECKING_DESTINATION,
-	/* Collecting file list */
 	GNOME_VFS_XFER_PHASE_COLLECTING,
-	/* File list collected (*) */
 	GNOME_VFS_XFER_PHASE_READYTOGO,
-	/* Opening source file for reading */
 	GNOME_VFS_XFER_PHASE_OPENSOURCE,
-	/* Creating target file for copy */
 	GNOME_VFS_XFER_PHASE_OPENTARGET,
-	/* Copying data from source to target (*) */
 	GNOME_VFS_XFER_PHASE_COPYING,
-	/* Moving file from source to target (*) */
 	GNOME_VFS_XFER_PHASE_MOVING,
-	/* Reading data from source file */
 	GNOME_VFS_XFER_PHASE_READSOURCE,
-	/* Writing data to target file */
 	GNOME_VFS_XFER_PHASE_WRITETARGET,
-	/* Closing source file */
 	GNOME_VFS_XFER_PHASE_CLOSESOURCE,
-	/* Closing target file */
 	GNOME_VFS_XFER_PHASE_CLOSETARGET,
-	/* Deleting source file */
 	GNOME_VFS_XFER_PHASE_DELETESOURCE,
-	/* Setting attributes on target file */
 	GNOME_VFS_XFER_PHASE_SETATTRIBUTES,
-	/* Go to the next file (*) */
 	GNOME_VFS_XFER_PHASE_FILECOMPLETED,
-	/* cleaning up after a move (removing source files, etc.) */
 	GNOME_VFS_XFER_PHASE_CLEANUP,
-	/* Operation finished (*) */
 	GNOME_VFS_XFER_PHASE_COMPLETED,
 	GNOME_VFS_XFER_NUM_PHASES
 } GnomeVFSXferPhase;
 
-/* Progress information for the transfer operation.  This is especially useful
-   for interactive programs.  */
+/**
+ * GnomeVFSXferProgressInfo:
+ *
+ * The GnomeVFSXferProgressInfo structure contains information about the state
+ * of the transfer in progress. This is specially useful for interative programs.
+ **/
 typedef struct {
 	/* Progress status (see above for a description).  */
 	GnomeVFSXferProgressStatus status;
@@ -211,22 +276,28 @@
 
 } GnomeVFSXferProgressInfo;
 
-/* This is the prototype for functions called during a transfer operation to
-   report progress.  If the return value is `FALSE' (0), the operation is
-   interrupted immediately: the transfer function returns with the value of
-   `vfs_status' if it is different from `GNOME_VFS_OK', or with
-   `GNOME_VFS_ERROR_INTERRUPTED' otherwise.  The effect of other values depend
-   on the value of `info->status':
-
-   - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_OK', the transfer
-     operation is resumed normally.
-
-   - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR', the return
-     value is interpreted as a `GnomeVFSXferErrorAction' and operation is
-     interrupted, continued or retried accordingly.
-
-   - If the status is `GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE', the return
-     value is interpreted as a `GnomeVFSXferOverwriteAction'.  */
+/**
+ * GnomeVFSXferProgressCallback:
+ * @info: Information about the transfer in progress
+ * @data:
+ * 
+ * This is the prototype for functions called during a transfer operation to
+ * report progress. Whenever this callback is called the value in info->status
+ * must be checked, it is here where the status of the transfer is passed and
+ * the effect of other values contained in @info depends on it.
+ * 
+ *    - If the status is #GNOME_VFS_XFER_PROGRESS_STATUS_OK, the transfer
+ *      operation is resumed normally.
+ *
+ *    - If the status is #GNOME_VFS_XFER_PROGRESS_STATUS_VFSERROR, the return
+ *      value is interpreted as a `GnomeVFSXferErrorAction' and operation is
+ *      interrupted, continued or retried accordingly.
+ *
+ *    - If the status is #GNOME_VFS_XFER_PROGRESS_STATUS_OVERWRITE, the return
+ *      value is interpreted as a `GnomeVFSXferOverwriteAction'. 
+ *
+ * Return Value: FALSE if the operation is interrupted inmediately, TRUE otherwise.
+ **/
 
 typedef gint (* GnomeVFSXferProgressCallback) 	(GnomeVFSXferProgressInfo *info,
 						 gpointer data);

Attachment: signature.asc
Description: This is a digitally signed message part



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]