Describe best practices for property names, and recommend against dash-separated...

Related to <https://bugs.freedesktop.org/show_bug.cgi?id=20948> whose
conclusion seemed to be that anything is allowed, but CamelCase is
considerably more interoperable.

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 86e2b9b7f570cab193a4cdedcb0a1ab4df8a80bc..88360af56a71827646ce69ed5368bb9337ba42f6 100644 (file)
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3066,6 +3066,22 @@
                                                       out DICT<STRING,VARIANT> props);
         </programlisting>
       </para>
+      <para>
+        It is conventional to give D-Bus properties names consisting of
+        capitalized words without punctuation ("CamelCase"), like
+        <link linkend="message-protocol-names-member">member names</link>.
+        For instance, the GObject property
+        <literal>connection-status</literal> or the Qt property
+        <literal>connectionStatus</literal> could be represented on D-Bus
+        as <literal>ConnectionStatus</literal>.
+      </para>
+      <para>
+        Strictly speaking, D-Bus property names are not required to follow
+        the same naming restrictions as member names, but D-Bus property
+        names that would not be valid member names (in particular,
+        GObject-style dash-separated property names) can cause interoperability
+        problems and should be avoided.
+      </para>
       <para>
         The available properties and whether they are writable can be determined
         by calling <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>,