[Pkg-privacy-commits] [libgsecuredelete] 37/168: Documentation updates & fixes.

[Ulrike Uhlig]

This is an automated email from the git hooks/post-receive script.

u-guest pushed a commit to branch master
in repository libgsecuredelete.

commit 7f8642b572181c39677878edb5a59bea813fc155
Author: Colomban Wendling <ban at herbesfolles.org>
Date:   Fri Oct 9 00:08:15 2009 +0200

    Documentation updates & fixes.
---
 gsecuredelete/async-operation.vala | 14 ++++++++++++--
 gsecuredelete/utils.vala           | 39 ++++++++++++++++++++++++++++++--------
 2 files changed, 43 insertions(+), 10 deletions(-)

diff --git a/gsecuredelete/async-operation.vala b/gsecuredelete/async-operation.vala
index 736b9c4..dc25df2 100644
--- a/gsecuredelete/async-operation.vala
+++ b/gsecuredelete/async-operation.vala
@@ -21,6 +21,15 @@ using GLib;
 
 namespace Gsd
 {
+  /** AsyncOperationError:
+   * 
+   * Error domain for the AsyncOperation class.
+   * @ARGS_ERROR: An error occurred during the build of the command's arguments.
+   * @CHILD_FAILED: The subprocess crashed or terminated with an error.
+   * @SUBCLASS_ERROR: Other error from a subclass of AsyncOperation. This is
+   *                  used as a workaround for the lack of error subclassing,
+   *                  disallowing to manage "generic" errors cleanly.
+   */
   public errordomain AsyncOperationError {
     ARGS_ERROR,
     CHILD_FAILED,
@@ -46,8 +55,7 @@ namespace Gsd
    * 
    * <warning>
    *   As it use a timeout function to watch the child, you need a GLib's
-   *   MainLoop for the watching process to work for the
-   *   asynchronous method.
+   *   MainLoop for the watching process to work for the asynchronous method.
    *   
    *   Yes, a thread might be a good thing, but have some limitations too:
    *   <list>
@@ -259,6 +267,8 @@ namespace Gsd
         }
       }
       
+      /* return false until subprocess terminated to keep being called by the
+       * timeout manager. */
       return ! finished;
     }
     
diff --git a/gsecuredelete/utils.vala b/gsecuredelete/utils.vala
index bccabf8..68dd687 100644
--- a/gsecuredelete/utils.vala
+++ b/gsecuredelete/utils.vala
@@ -19,7 +19,16 @@
 
 namespace Gsd
 {
-  
+  /** FDError:
+   * 
+   * Error domain for the FD namespace functions. It is mainly a wrapper around
+   * some errnos to have exceptions for them.
+   * 
+   * @KILL_ERROR: A call to Posix.kill() failed.
+   * @READ_ERROR: A call to Posix.read() failed.
+   * @SELECT_ERROR: A call to Posix.select() failed.
+   * @WAITPID_ERROR: A call to Posix.waitpid() failed.
+   */
   public errordomain FDError {
     KILL_ERROR,
     READ_ERROR,
@@ -27,14 +36,16 @@ namespace Gsd
     WAITPID_ERROR,
   }
   
-  namespace FD {
+  namespace FD
+  {
     /** read_ready:
      * @fd: a file descriptor
      * @error: return location for an error string on error, or NULL to ignore
      *         errors.
      * 
-     * Gets whether a file descriptor is ready to be read or not. Ready means that
-     * reading data from it would not be blocking, as there is data to be read.
+     * Gets whether a file descriptor is ready to be read or not. Ready means
+     * that reading data from it would not be blocking, as there is data to be
+     * read.
      * 
      * Returns: %TRUE if the file is read, %FALSE otherwise.
      */
@@ -62,7 +73,6 @@ namespace Gsd
     }
     
     /** read_string:
-     * 
      * @fd: a file descriptor
      * @n_bytes: number of bytes to read from @fd, or -1 to read all @fd
      * 
@@ -125,9 +135,22 @@ namespace Gsd
       return (string?) (owned) buf;
     }
     
-    /* Counts the number of occurrence of a given byte in a file descriptor.
-     * This function is non-blocking and returns 0 if there is no
-     * data in the buffer rather than blocking waiting for data to read. */
+    /** count_ready_bytes:
+     * @fd: a valid file descriptor
+     * @byte: the byte to cont in @fd
+     * @bufsize: the size of the buffer used to cache the file's content.
+     *           Tweaking it may improve the performances with different amount
+     *           of data in @fd: the better value is the closer to the total
+     *           number of bytes that will be read (the size of the file's
+     *           content) or a multiple of it if it is a too big value to be
+     *           reasonably allocated at once.
+     * 
+     * Counts the number of occurrence of a given byte in a file descriptor.
+     * This function is non-blocking and returns 0 if there is no data in the
+     * buffer rather than blocking waiting for data to read.
+     * 
+     * Returns: the number of occurrences of @byte in @fd.
+     */
     public uint count_ready_bytes (int    fd,
                                    int    byte,
                                    size_t bufsize = 16)

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/libgsecuredelete.git