Documentation tweaks

Add Since tags, etc.

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>
 

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

glib/glib-unix.c

@@ -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).
  *
@@ -148,6 +149,8 @@ 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,
@@ -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,6 +247,8 @@ 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,