From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Tue, 17 May 2011 16:10:36 +0000 (+0100)
Subject: Describe best practices for property names, and recommend against dash-separated... 
X-Git-Tag: dbus-1.5.10~55^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1909039b191f0ac1c1fa2aeb9b9053b921471f1b;p=thirdparty%2Fdbus.git

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

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 86e2b9b7f..88360af56 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -3066,6 +3066,22 @@
                                                       out DICT&lt;STRING,VARIANT&gt; 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>,