GNOME.org
 

[glib] Documentation tweaks

commit d35e83d3372ca484a765dfca2ded8ed5adb61e5a
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat May 28 21:12:52 2011 -0400

    Documentation tweaks
    
    Add Since tags, etc.

 docs/reference/glib/glib-sections.txt |    1 +
 glib/gatomic.c                        |   62 ++++++++++++++++++++++++++-------
 glib/glib-unix.c                      |   53 ++++++++++++++++------------
 glib/glib-unix.h                      |   20 +++++-----
 4 files changed, 90 insertions(+), 46 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index a290ac1..b8dbbb9 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -1943,6 +1943,7 @@ G_UNIX_ERROR
 g_unix_open_pipe
 g_unix_signal_source_new
 g_unix_signal_add_watch_full
+g_unix_set_fd_nonblocking
 
 </SECTION>
 
diff --git a/glib/gatomic.c b/glib/gatomic.c
index 0da78b9..5bb3723 100644
--- a/glib/gatomic.c
+++ b/glib/gatomic.c
@@ -94,8 +94,8 @@
  *
  * Gets the current value of @atomic.
  *
- * This call acts as a full compiler and hardware memory barrier (before
- * the get).
+ * This call acts as a full compiler and hardware
+ * memory barrier (before the get).
  *
  * Returns: the value of the integer
  *
@@ -114,11 +114,11 @@ gint
  *
  * Sets the value of @atomic to @newval.
  *
- * This call acts as a full compiler and hardware memory barrier (after
- * the set).
+ * This call acts as a full compiler and hardware
+ * memory barrier (after the set).
  *
  * Since: 2.4
- **/
+ */
 void
 (g_atomic_int_set) (volatile gint *atomic,
                     gint           newval)
@@ -132,6 +132,9 @@ void
  *
  * Increments the value of @atomic by 1.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ * atomic += 1; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Since: 2.4
@@ -148,6 +151,9 @@ void
  *
  * Decrements the value of @atomic by 1.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ * atomic -= 1; return (* atomic == 0); }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: %TRUE if the resultant value is zero
@@ -166,11 +172,14 @@ gboolean
  * @oldval: the value to compare with
  * @newval: the value to conditionally replace with
  *
- * Compares @atomic to @oldval and, if equal, sets it to @newval.  If
- * @atomic was not equal to @oldval then no change occurs.
+ * Compares @atomic to @oldval and, if equal, sets it to @newval.
+ * If @atomic was not equal to @oldval then no change occurs.
  *
  * This compare and exchange is done atomically.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ if (* atomic == @oldval) { * atomic = @newval; return TRUE; } else return FALSE; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: %TRUE if the exchange took place
@@ -192,6 +201,9 @@ gboolean
  *
  * Atomically adds @val to the value of @atomic.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic += @val; return tmp; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: the value of @atomic before the add, signed
@@ -215,6 +227,9 @@ gint
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic &= @val; return tmp; }</literal>
+ *
  * Returns: the value of @atomic before the operation, unsigned
  *
  * Since: 2.30
@@ -234,6 +249,9 @@ guint
  * Performs an atomic bitwise 'or' of the value of @atomic and @val,
  * storing the result back in @atomic.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic |= @val; return tmp; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: the value of @atomic before the operation, unsigned
@@ -255,6 +273,9 @@ guint
  * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
  * storing the result back in @atomic.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic ^= @val; return tmp; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: the value of @atomic before the operation, unsigned
@@ -275,8 +296,8 @@ guint
  *
  * Gets the current value of @atomic.
  *
- * This call acts as a full compiler and hardware memory barrier (before
- * the get).
+ * This call acts as a full compiler and hardware
+ * memory barrier (before the get).
  *
  * Returns: the value of the pointer
  *
@@ -295,8 +316,8 @@ gpointer
  *
  * Sets the value of @atomic to @newval.
  *
- * This call acts as a full compiler and hardware memory barrier (after
- * the set).
+ * This call acts as a full compiler and hardware
+ * memory barrier (after the set).
  *
  * Since: 2.4
  **/
@@ -313,11 +334,14 @@ void
  * @oldval: the value to compare with
  * @newval: the value to conditionally replace with
  *
- * Compares @atomic to @oldval and, if equal, sets it to @newval.  If
- * @atomic was not equal to @oldval then no change occurs.
+ * Compares @atomic to @oldval and, if equal, sets it to @newval.
+ * If @atomic was not equal to @oldval then no change occurs.
  *
  * This compare and exchange is done atomically.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ if (* atomic == @oldval) { * atomic = @newval; return TRUE; } else return FALSE; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: %TRUE if the exchange took place
@@ -340,6 +364,9 @@ gboolean
  *
  * Atomically adds @val to the value of @atomic.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic += @val; return tmp; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: the value of @atomic before the add, signed
@@ -361,6 +388,9 @@ gssize
  * Performs an atomic bitwise 'and' of the value of @atomic and @val,
  * storing the result back in @atomic.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic &= @val; return tmp; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: the value of @atomic before the operation, unsigned
@@ -382,6 +412,9 @@ gsize
  * Performs an atomic bitwise 'or' of the value of @atomic and @val,
  * storing the result back in @atomic.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic |= @val; return tmp; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: the value of @atomic before the operation, unsigned
@@ -403,6 +436,9 @@ gsize
  * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
  * storing the result back in @atomic.
  *
+ * Think of this operation as an atomic version of
+ * <literal>{ tmp = *atomic; * atomic ^= @val; return tmp; }</literal>
+ *
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Returns: the value of @atomic before the operation, unsigned
diff --git a/glib/glib-unix.c b/glib/glib-unix.c
index 7471ddb..14a2ef3 100644
--- a/glib/glib-unix.c
+++ b/glib/glib-unix.c
@@ -1,7 +1,7 @@
 /* GLIB - Library of useful routines for C programming
  * Copyright (C) 2011 Red Hat, Inc.
  *
- * glib-unix.c: UNIX specific API wrappers and convenience functions 
+ * glib-unix.c: UNIX specific API wrappers and convenience functions
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -10,7 +10,7 @@
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
@@ -54,21 +54,21 @@ g_unix_set_error_from_errno (GError **error)
 {
   int saved_errno = errno;
   g_set_error_literal (error,
-		       G_UNIX_ERROR,
-		       0,
-		       g_strerror (errno));
+                       G_UNIX_ERROR,
+                       0,
+                       g_strerror (errno));
   errno = saved_errno;
   return FALSE;
 }
 
 static gboolean
 g_unix_set_error_from_errno_saved (GError **error,
-				    int      saved_errno)
+                                    int      saved_errno)
 {
   g_set_error_literal (error,
-		       G_UNIX_ERROR,
-		       0,
-		       g_strerror (saved_errno));
+                       G_UNIX_ERROR,
+                       0,
+                       g_strerror (saved_errno));
   errno = saved_errno;
   return FALSE;
 }
@@ -82,11 +82,12 @@ g_unix_set_error_from_errno_saved (GError **error,
  * Similar to the UNIX pipe() call, but on modern systems like Linux
  * uses the pipe2() system call, which atomically creates a pipe with
  * the configured flags.  The only supported flag currently is
- * %FD_CLOEXEC.  If for example you want to configure %O_NONBLOCK, that
- * must still be done separately with fcntl().
+ * %FD_CLOEXEC.  If for example you want to configure %O_NONBLOCK,
+ * that must still be done separately with fcntl().
  *
- * <note>This function does *not* take %O_CLOEXEC, it takes %FD_CLOEXEC as if
- * for fcntl(); these are different on Linux/glibc.</note>
+ * <note>This function does *not* take %O_CLOEXEC, it takes
+ * %FD_CLOEXEC as if for fcntl(); these are different on
+ * Linux/glibc.</note>
  *
  * Returns: %TRUE on success, %FALSE if not (and errno will be set).
  *
@@ -94,8 +95,8 @@ g_unix_set_error_from_errno_saved (GError **error,
  */
 gboolean
 g_unix_open_pipe (int     *fds,
-		  int      flags,
-		  GError **error)
+                  int      flags,
+                  GError **error)
 {
   int ecode;
 
@@ -148,11 +149,13 @@ g_unix_open_pipe (int     *fds,
  * on some older ones may use %O_NDELAY.
  *
  * Returns: %TRUE if successful
+ *
+ * Since: 2.30
  */
 gboolean
-g_unix_set_fd_nonblocking (gint       fd, 
-			   gboolean   nonblock,
-			   GError   **error)
+g_unix_set_fd_nonblocking (gint       fd,
+                           gboolean   nonblock,
+                           GError   **error)
 {
 #ifdef F_GETFL
   glong fcntl_flags;
@@ -196,7 +199,7 @@ g_unix_set_fd_nonblocking (gint       fd,
  * be monitored.  Note that unlike the UNIX default, all sources which
  * have created a watch will be dispatched, regardless of which
  * underlying thread invoked g_unix_signal_create_watch().
- * 
+ *
  * For example, an effective use of this function is to handle SIGTERM
  * cleanly; flushing any outstanding files, and then calling
  * g_main_loop_quit ().  It is not safe to do any of this a regular
@@ -219,6 +222,8 @@ g_unix_set_fd_nonblocking (gint       fd,
  * executed.
  *
  * Returns: A newly created #GSource
+ *
+ * Since: 2.30
  */
 GSource *
 g_unix_signal_source_new (int signum)
@@ -242,13 +247,15 @@ g_unix_signal_source_new (int signum)
  * using g_source_remove().
  *
  * Returns: An ID (greater than 0) for the event source
+ *
+ * Since: 2.30
  */
 guint
 g_unix_signal_add_watch_full (int            signum,
-			      int            priority,
-			      GSourceFunc    handler,
-			      gpointer       user_data,
-			      GDestroyNotify notify)
+                              int            priority,
+                              GSourceFunc    handler,
+                              gpointer       user_data,
+                              GDestroyNotify notify)
 {
   guint id;
   GSource *source;
diff --git a/glib/glib-unix.h b/glib/glib-unix.h
index d1e5ca2..b136fe3 100644
--- a/glib/glib-unix.h
+++ b/glib/glib-unix.h
@@ -57,20 +57,20 @@
 
 GQuark g_unix_error_quark (void);
 
-gboolean g_unix_open_pipe (gint      *fds,
-			   gint       flags,
-			   GError   **error);
+gboolean g_unix_open_pipe (gint    *fds,
+                           gint     flags,
+                           GError **error);
 
 gboolean g_unix_set_fd_nonblocking (gint       fd,
-				    gboolean   nonblock,
-				    GError   **error);
+                                    gboolean   nonblock,
+                                    GError   **error);
 
 GSource *g_unix_signal_source_new     (gint signum);
 
-guint    g_unix_signal_add_watch_full (gint            signum,
-				       gint            priority,
-				       GSourceFunc     handler,
-				       gpointer        user_data,
-				       GDestroyNotify  notify);
+guint    g_unix_signal_add_watch_full (gint           signum,
+                                       gint           priority,
+                                       GSourceFunc    handler,
+                                       gpointer       user_data,
+                                       GDestroyNotify notify);
 
 #endif
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]