spec: Move RequestName API description to list of methods

Tom Gundersen pointed out that RequestName, ReleaseName and
ListQueuedOwners were documented in their own section instead of being
put together with the other method calls, which makes it more difficult
to apply changes consistently across all methods.

I'm moving them one at a time to make the changes reviewable, since
the diff resulting from moving all three as a unit is too large to
review sensibly.

Signed-off-by: Simon McVittie <smcv@collabora.com>

1 files changed, 241 insertions, 240 deletions

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 0f0ca5ae..b9e2c02b 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -4254,246 +4254,6 @@
         <literal>org.freedesktop.DBus.ReleaseName</literal> message.
       </para>
 
-      <sect3 id="bus-messages-request-name">
-        <title><literal>org.freedesktop.DBus.RequestName</literal></title>
-        <para>
-          As a method:
-          <programlisting>
-            UINT32 RequestName (in STRING name, in UINT32 flags)
-          </programlisting>
-          Message arguments:
-          <informaltable>
-            <tgroup cols="3">
-              <thead>
-                <row>
-                  <entry>Argument</entry>
-                  <entry>Type</entry>
-                  <entry>Description</entry>
-                </row>
-              </thead>
-              <tbody>
-                <row>
-                  <entry>0</entry>
-                  <entry>STRING</entry>
-                  <entry>Name to request</entry>
-                </row>
-                <row>
-                  <entry>1</entry>
-                  <entry>UINT32</entry>
-                  <entry>Flags</entry>
-                </row>
-              </tbody>
-            </tgroup>
-          </informaltable>
-          Reply arguments:
-          <informaltable>
-            <tgroup cols="3">
-              <thead>
-                <row>
-                  <entry>Argument</entry>
-                  <entry>Type</entry>
-                  <entry>Description</entry>
-                </row>
-              </thead>
-              <tbody>
-                <row>
-                  <entry>0</entry>
-                  <entry>UINT32</entry>
-                  <entry>Return value</entry>
-                </row>
-              </tbody>
-            </tgroup>
-          </informaltable>
-        </para>
-        <para>
-          This method call should be sent to
-          <literal>org.freedesktop.DBus</literal> and asks the message bus to
-          assign the given name to the method caller. Each name maintains a
-          queue of possible owners, where the head of the queue is the primary
-          or current owner of the name. Each potential owner in the queue
-          maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
-          DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
-          call.  When RequestName is invoked the following occurs:
-          <itemizedlist>
-            <listitem>
-              <para>
-                If the method caller is currently the primary owner of the name,
-                the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
-                values are updated with the values from the new RequestName call,
-                and nothing further happens.
-              </para>
-            </listitem>
-
-            <listitem>
-              <para>
-                If the current primary owner (head of the queue) has
-                DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
-                invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
-                the caller of RequestName replaces the current primary owner at
-                the head of the queue and the current primary owner moves to the
-                second position in the queue. If the caller of RequestName was
-                in the queue previously its flags are updated with the values from
-                the new RequestName in addition to moving it to the head of the queue.
-              </para>
-            </listitem>
-
-            <listitem>
-              <para>
-                If replacement is not possible, and the method caller is
-                currently in the queue but not the primary owner, its flags are
-                updated with the values from the new RequestName call.
-              </para>
-            </listitem>
-
-            <listitem>
-              <para>
-                If replacement is not possible, and the method caller is
-                currently not in the queue, the method caller is appended to the
-                queue.
-              </para>
-            </listitem>
-
-            <listitem>
-              <para>
-                If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
-                set and is not the primary owner, it is removed from the
-                queue. This can apply to the previous primary owner (if it
-                was replaced) or the method caller (if it updated the
-                DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
-                queue, or if it was just added to the queue with that flag set).
-              </para>
-            </listitem>
-          </itemizedlist>
-        </para>
-        <para>
-          Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
-          queue," even if another application already in the queue had specified
-          DBUS_NAME_FLAG_REPLACE_EXISTING.  This comes up if a primary owner
-          that does not allow replacement goes away, and the next primary owner
-          does allow replacement. In this case, queued items that specified
-          DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
-          automatically replace the new primary owner. In other words,
-          DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
-          time RequestName is called. This is deliberate to avoid an infinite loop
-          anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
-          and DBUS_NAME_FLAG_REPLACE_EXISTING.
-        </para>
-        <para>
-          The flags argument contains any of the following values logically ORed
-          together:
-
-          <informaltable>
-            <tgroup cols="3">
-              <thead>
-                <row>
-                  <entry>Conventional Name</entry>
-                  <entry>Value</entry>
-                  <entry>Description</entry>
-                </row>
-              </thead>
-              <tbody>
-                <row>
-                  <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
-                  <entry>0x1</entry>
-                  <entry>
-
-                    If an application A specifies this flag and succeeds in
-                    becoming the owner of the name, and another application B
-                    later calls RequestName with the
-                    DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
-                    will lose ownership and receive a
-                    <literal>org.freedesktop.DBus.NameLost</literal> signal, and
-                    application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
-                    is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
-                    is not specified by application B, then application B will not replace
-                    application A as the owner.
-
-                  </entry>
-                </row>
-                <row>
-                  <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
-                  <entry>0x2</entry>
-                  <entry>
-
-                    Try to replace the current owner if there is one. If this
-                    flag is not set the application will only become the owner of
-                    the name if there is no current owner. If this flag is set,
-                    the application will replace the current owner if
-                    the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
-
-                  </entry>
-                </row>
-                <row>
-                  <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
-                  <entry>0x4</entry>
-                  <entry>
-
-                    Without this flag, if an application requests a name that is
-                    already owned, the application will be placed in a queue to
-                    own the name when the current owner gives it up. If this
-                    flag is given, the application will not be placed in the
-                    queue, the request for the name will simply fail.  This flag
-                    also affects behavior when an application is replaced as
-                    name owner; by default the application moves back into the
-                    waiting queue, unless this flag was provided when the application
-                    became the name owner.
-
-                  </entry>
-                </row>
-              </tbody>
-            </tgroup>
-          </informaltable>
-
-          The return code can be one of the following values:
-
-          <informaltable>
-            <tgroup cols="3">
-              <thead>
-                <row>
-                  <entry>Conventional Name</entry>
-                  <entry>Value</entry>
-                  <entry>Description</entry>
-                </row>
-              </thead>
-              <tbody>
-                <row>
-                  <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
-                  <entry>1</entry> <entry>The caller is now the primary owner of
-                  the name, replacing any previous owner. Either the name had no
-                  owner before, or the caller specified
-                  DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
-                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
-                </row>
-                <row>
-                  <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
-                  <entry>2</entry>
-
-                  <entry>The name already had an owner,
-                    DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
-                    the current owner did not specify
-                    DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
-                    application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
-                    </entry>
-                </row>
-                <row>
-                  <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
-                  <entry>The name already has an owner,
-                  DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
-                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
-                  current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
-                  specified by the requesting application.</entry>
-                </row>
-                <row>
-                  <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
-                  <entry>4</entry>
-                  <entry>The application trying to request ownership of a name is already the owner of it.</entry>
-                </row>
-              </tbody>
-            </tgroup>
-          </informaltable>
-        </para>
-       </sect3>
-
        <sect3 id="bus-messages-release-name">
         <title><literal>org.freedesktop.DBus.ReleaseName</literal></title>
         <para>
@@ -5654,6 +5414,247 @@
           communication channel).
         </para>
       </sect3>
+
+      <sect3 id="bus-messages-request-name">
+        <title><literal>org.freedesktop.DBus.RequestName</literal></title>
+        <para>
+          As a method:
+          <programlisting>
+            UINT32 RequestName (in STRING name, in UINT32 flags)
+          </programlisting>
+          Message arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>STRING</entry>
+                  <entry>Name to request</entry>
+                </row>
+                <row>
+                  <entry>1</entry>
+                  <entry>UINT32</entry>
+                  <entry>Flags</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          Reply arguments:
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Argument</entry>
+                  <entry>Type</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>0</entry>
+                  <entry>UINT32</entry>
+                  <entry>Return value</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+        <para>
+          This method call should be sent to
+          <literal>org.freedesktop.DBus</literal> and asks the message bus to
+          assign the given name to the method caller. Each name maintains a
+          queue of possible owners, where the head of the queue is the primary
+          or current owner of the name. Each potential owner in the queue
+          maintains the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and
+          DBUS_NAME_FLAG_DO_NOT_QUEUE settings from its latest RequestName
+          call.  When RequestName is invoked the following occurs:
+          <itemizedlist>
+            <listitem>
+              <para>
+                If the method caller is currently the primary owner of the name,
+                the DBUS_NAME_FLAG_ALLOW_REPLACEMENT and DBUS_NAME_FLAG_DO_NOT_QUEUE
+                values are updated with the values from the new RequestName call,
+                and nothing further happens.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If the current primary owner (head of the queue) has
+                DBUS_NAME_FLAG_ALLOW_REPLACEMENT set, and the RequestName
+                invocation has the DBUS_NAME_FLAG_REPLACE_EXISTING flag, then
+                the caller of RequestName replaces the current primary owner at
+                the head of the queue and the current primary owner moves to the
+                second position in the queue. If the caller of RequestName was
+                in the queue previously its flags are updated with the values from
+                the new RequestName in addition to moving it to the head of the queue.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If replacement is not possible, and the method caller is
+                currently in the queue but not the primary owner, its flags are
+                updated with the values from the new RequestName call.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If replacement is not possible, and the method caller is
+                currently not in the queue, the method caller is appended to the
+                queue.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                If any connection in the queue has DBUS_NAME_FLAG_DO_NOT_QUEUE
+                set and is not the primary owner, it is removed from the
+                queue. This can apply to the previous primary owner (if it
+                was replaced) or the method caller (if it updated the
+                DBUS_NAME_FLAG_DO_NOT_QUEUE flag while still stuck in the
+                queue, or if it was just added to the queue with that flag set).
+              </para>
+            </listitem>
+          </itemizedlist>
+        </para>
+        <para>
+          Note that DBUS_NAME_FLAG_REPLACE_EXISTING results in "jumping the
+          queue," even if another application already in the queue had specified
+          DBUS_NAME_FLAG_REPLACE_EXISTING.  This comes up if a primary owner
+          that does not allow replacement goes away, and the next primary owner
+          does allow replacement. In this case, queued items that specified
+          DBUS_NAME_FLAG_REPLACE_EXISTING <emphasis>do not</emphasis>
+          automatically replace the new primary owner. In other words,
+          DBUS_NAME_FLAG_REPLACE_EXISTING is not saved, it is only used at the
+          time RequestName is called. This is deliberate to avoid an infinite loop
+          anytime two applications are both DBUS_NAME_FLAG_ALLOW_REPLACEMENT
+          and DBUS_NAME_FLAG_REPLACE_EXISTING.
+        </para>
+        <para>
+          The flags argument contains any of the following values logically ORed
+          together:
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Conventional Name</entry>
+                  <entry>Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>DBUS_NAME_FLAG_ALLOW_REPLACEMENT</entry>
+                  <entry>0x1</entry>
+                  <entry>
+
+                    If an application A specifies this flag and succeeds in
+                    becoming the owner of the name, and another application B
+                    later calls RequestName with the
+                    DBUS_NAME_FLAG_REPLACE_EXISTING flag, then application A
+                    will lose ownership and receive a
+                    <literal>org.freedesktop.DBus.NameLost</literal> signal, and
+                    application B will become the new owner. If DBUS_NAME_FLAG_ALLOW_REPLACEMENT
+                    is not specified by application A, or DBUS_NAME_FLAG_REPLACE_EXISTING
+                    is not specified by application B, then application B will not replace
+                    application A as the owner.
+
+                  </entry>
+                </row>
+                <row>
+                  <entry>DBUS_NAME_FLAG_REPLACE_EXISTING</entry>
+                  <entry>0x2</entry>
+                  <entry>
+
+                    Try to replace the current owner if there is one. If this
+                    flag is not set the application will only become the owner of
+                    the name if there is no current owner. If this flag is set,
+                    the application will replace the current owner if
+                    the current owner specified DBUS_NAME_FLAG_ALLOW_REPLACEMENT.
+
+                  </entry>
+                </row>
+                <row>
+                  <entry>DBUS_NAME_FLAG_DO_NOT_QUEUE</entry>
+                  <entry>0x4</entry>
+                  <entry>
+
+                    Without this flag, if an application requests a name that is
+                    already owned, the application will be placed in a queue to
+                    own the name when the current owner gives it up. If this
+                    flag is given, the application will not be placed in the
+                    queue, the request for the name will simply fail.  This flag
+                    also affects behavior when an application is replaced as
+                    name owner; by default the application moves back into the
+                    waiting queue, unless this flag was provided when the application
+                    became the name owner.
+
+                  </entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+
+          The return code can be one of the following values:
+
+          <informaltable>
+            <tgroup cols="3">
+              <thead>
+                <row>
+                  <entry>Conventional Name</entry>
+                  <entry>Value</entry>
+                  <entry>Description</entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</entry>
+                  <entry>1</entry> <entry>The caller is now the primary owner of
+                  the name, replacing any previous owner. Either the name had no
+                  owner before, or the caller specified
+                  DBUS_NAME_FLAG_REPLACE_EXISTING and the current owner specified
+                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT.</entry>
+                </row>
+                <row>
+                  <entry>DBUS_REQUEST_NAME_REPLY_IN_QUEUE</entry>
+                  <entry>2</entry>
+
+                  <entry>The name already had an owner,
+                    DBUS_NAME_FLAG_DO_NOT_QUEUE was not specified, and either
+                    the current owner did not specify
+                    DBUS_NAME_FLAG_ALLOW_REPLACEMENT or the requesting
+                    application did not specify DBUS_NAME_FLAG_REPLACE_EXISTING.
+                    </entry>
+                </row>
+                <row>
+                  <entry>DBUS_REQUEST_NAME_REPLY_EXISTS</entry> <entry>3</entry>
+                  <entry>The name already has an owner,
+                  DBUS_NAME_FLAG_DO_NOT_QUEUE was specified, and either
+                  DBUS_NAME_FLAG_ALLOW_REPLACEMENT was not specified by the
+                  current owner, or DBUS_NAME_FLAG_REPLACE_EXISTING was not
+                  specified by the requesting application.</entry>
+                </row>
+                <row>
+                  <entry>DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</entry>
+                  <entry>4</entry>
+                  <entry>The application trying to request ownership of a name is already the owner of it.</entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+        </para>
+       </sect3>
+
       <sect3 id="bus-messages-list-names">
         <title><literal>org.freedesktop.DBus.ListNames</literal></title>
         <para>