[glib: 29/30] docs: Document not to use `volatile` qualifiers

[Philip Withnall <pwithnall src gnome org>]

commit 83e48d8ac1fee98059e2305d8909dca26190bddc
Author: Philip Withnall <pwithnall endlessos org>
Date:   Tue Nov 17 10:15:15 2020 +0000

    docs: Document not to use `volatile` qualifiers
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Fixes: #600

 gio/gdbusconnection.c | 12 +++++++++---
 gio/gdbuserror.c      |  3 +++
 glib/gatomic.c        | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 glib/gthread.c        |  6 ++++++
 4 files changed, 66 insertions(+), 3 deletions(-)
---
diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c
index 91c365e80..65939a4d2 100644
--- a/gio/gdbusconnection.c
+++ b/gio/gdbusconnection.c
@@ -1708,7 +1708,9 @@ g_dbus_connection_send_message_unlocked (GDBusConnection   *connection,
  * will be assigned by @connection and set on @message via
  * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
  * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
+ * submitting the message to the underlying transport. While it has a `volatile`
+ * qualifier, this is a historical artifact and the argument passed to it should
+ * not be `volatile`.
  *
  * If @connection is closed then the operation will fail with
  * %G_IO_ERROR_CLOSED. If @message is not well-formed,
@@ -1979,7 +1981,9 @@ g_dbus_connection_send_message_with_reply_unlocked (GDBusConnection     *connect
  * will be assigned by @connection and set on @message via
  * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
  * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
+ * submitting the message to the underlying transport. While it has a `volatile`
+ * qualifier, this is a historical artifact and the argument passed to it should
+ * not be `volatile`.
  *
  * If @connection is closed then the operation will fail with
  * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
@@ -2105,7 +2109,9 @@ send_message_with_reply_sync_cb (GDBusConnection *connection,
  * will be assigned by @connection and set on @message via
  * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the
  * serial number used will be written to this location prior to
- * submitting the message to the underlying transport.
+ * submitting the message to the underlying transport. While it has a `volatile`
+ * qualifier, this is a historical artifact and the argument passed to it should
+ * not be `volatile`.
  *
  * If @connection is closed then the operation will fail with
  * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will
diff --git a/gio/gdbuserror.c b/gio/gdbuserror.c
index b03a33f27..4ad97bb6e 100644
--- a/gio/gdbuserror.c
+++ b/gio/gdbuserror.c
@@ -177,6 +177,9 @@ g_dbus_error_quark (void)
  *
  * Helper function for associating a #GError error domain with D-Bus error names.
  *
+ * While @quark_volatile has a `volatile` qualifier, this is a historical
+ * artifact and the argument passed to it should not be `volatile`.
+ *
  * Since: 2.26
  */
 void
diff --git a/glib/gatomic.c b/glib/gatomic.c
index 67f5ba6b4..0bc67aa35 100644
--- a/glib/gatomic.c
+++ b/glib/gatomic.c
@@ -105,6 +105,9 @@
  * This call acts as a full compiler and hardware
  * memory barrier (before the get).
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of the integer
  *
  * Since: 2.4
@@ -125,6 +128,9 @@ gint
  * This call acts as a full compiler and hardware
  * memory barrier (after the set).
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Since: 2.4
  */
 void
@@ -144,6 +150,9 @@ void
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Since: 2.4
  **/
 void
@@ -163,6 +172,9 @@ void
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: %TRUE if the resultant value is zero
  *
  * Since: 2.4
@@ -189,6 +201,9 @@ gboolean
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: %TRUE if the exchange took place
  *
  * Since: 2.4
@@ -216,6 +231,9 @@ gboolean
  * Before version 2.30, this function did not return a value
  * (but g_atomic_int_exchange_and_add() did, and had the same meaning).
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the add, signed
  *
  * Since: 2.4
@@ -240,6 +258,9 @@ gint
  * Think of this operation as an atomic version of
  * `{ tmp = *atomic; *atomic &= val; return tmp; }`.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the operation, unsigned
  *
  * Since: 2.30
@@ -264,6 +285,9 @@ guint
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the operation, unsigned
  *
  * Since: 2.30
@@ -288,6 +312,9 @@ guint
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the operation, unsigned
  *
  * Since: 2.30
@@ -309,6 +336,9 @@ guint
  * This call acts as a full compiler and hardware
  * memory barrier (before the get).
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of the pointer
  *
  * Since: 2.4
@@ -329,6 +359,9 @@ gpointer
  * This call acts as a full compiler and hardware
  * memory barrier (after the set).
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Since: 2.4
  **/
 void
@@ -354,6 +387,9 @@ void
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: %TRUE if the exchange took place
  *
  * Since: 2.4
@@ -379,6 +415,9 @@ gboolean
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the add, signed
  *
  * Since: 2.30
@@ -403,6 +442,9 @@ gssize
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the operation, unsigned
  *
  * Since: 2.30
@@ -427,6 +469,9 @@ gsize
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the operation, unsigned
  *
  * Since: 2.30
@@ -451,6 +496,9 @@ gsize
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
+ * While @atomic has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: the value of @atomic before the operation, unsigned
  *
  * Since: 2.30
diff --git a/glib/gthread.c b/glib/gthread.c
index 612a9739f..29216d7fd 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -686,6 +686,9 @@ g_once_impl (GOnce       *once,
  *   // use initialization_value here
  * ]|
  *
+ * While @location has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Returns: %TRUE if the initialization section should be entered,
  *     %FALSE and blocks otherwise
  *
@@ -725,6 +728,9 @@ gboolean
  * releases concurrent threads blocking in g_once_init_enter() on this
  * initialization variable.
  *
+ * While @location has a `volatile` qualifier, this is a historical artifact and
+ * the pointer passed to it should not be `volatile`.
+ *
  * Since: 2.14
  */
 void