From fc2ec16d3578631c9f51af65cf9d47b3dc38f0aa Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Tue, 23 Sep 2014 17:43:30 +0100
Subject: [PATCH] Expand documentation of NO_REPLY_EXPECTED

The message type is more important than whether NO_REPLY_EXPECTED is
set, when deciding whether a reply is expected. This documents
existing practice in at least libdbus, GDBus and dbus-daemon.

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=75749
---
 doc/dbus-specification.xml | 34 ++++++++++++++++++++++++++--------
 1 file changed, 26 insertions(+), 8 deletions(-)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 6c26296..337fe83 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -1303,7 +1303,8 @@
               <row>
                 <entry><literal>METHOD_CALL</literal></entry>
                 <entry>1</entry>
-                <entry>Method call.</entry>
+                <entry>Method call. This message type may prompt a
+                  reply.</entry>
               </row>
               <row>
                 <entry><literal>METHOD_RETURN</literal></entry>
@@ -1340,11 +1341,26 @@
               <row>
                 <entry><literal>NO_REPLY_EXPECTED</literal></entry>
                 <entry>0x1</entry>
-                <entry>This message does not expect method return replies or
-                error replies; the reply can be omitted as an
-                optimization. However, it is compliant with this specification
-                to return the reply despite this flag and the only harm 
-                  from doing so is extra network traffic.
+                <entry>
+                  <para>
+                    This message does not expect method return replies or
+                    error replies, even if it is of a type that can
+                    have a reply; the reply can be omitted as an
+                    optimization. It is compliant with this specification
+                    to return the reply despite this flag, although doing
+                    so on a bus with a non-trivial security policy
+                    (such as the well-known system bus) may result in
+                    access denial messages being logged for the reply.
+                  </para>
+                  <para>
+                    Note that METHOD_CALL is the only message type currently
+                    defined in this specification that can expect a reply,
+                    so the presence or absence of this flag in the other
+                    three message types that are currently
+                    documented is meaningless: replies to those message
+                    types should not be sent, whether this flag is present
+                    or not.
+                  </para>
                 </entry>
               </row>
               <row>
@@ -5305,7 +5321,9 @@
         <literal>DESTINATION</literal> field is absent, it is considered to
         be a <firstterm>broadcast signal</firstterm>, and is sent to all
         applications with <firstterm>message matching rules</firstterm> that
-        match the message. Most signal messages are broadcasts.
+        match the message. Most signal messages are broadcasts, and
+        no other message types currently defined in this specification
+        may be broadcast.
       </para>
 
       <para>
@@ -5345,7 +5363,7 @@
       <para>
         Message bus implementations may impose a security policy which
         prevents certain messages from being sent or received.
-        When a message cannot be sent or received due to a security
+        When a method call message cannot be sent or received due to a security
         policy, the message bus should send an error reply, unless the
         original message had the <literal>NO_REPLY</literal> flag.
       </para>
-- 
2.1.1