From f370a36b5d95dc8f85205b49c54f0da7be905bbf Mon Sep 17 00:00:00 2001
From: Philip Withnall <philip.withnall@collabora.co.uk>
Date: Fri, 6 Feb 2015 09:45:50 +0000
Subject: [PATCH 3/3] fixup! doc: Add a guide to designing D-Bus APIs

---
 doc/dbus-api-design.duck | 65 +++++++++++++++++++++++++++---------------------
 1 file changed, 37 insertions(+), 28 deletions(-)

diff --git a/doc/dbus-api-design.duck b/doc/dbus-api-design.duck
index 90e9482..9430d4e 100644
--- a/doc/dbus-api-design.duck
+++ b/doc/dbus-api-design.duck
@@ -64,8 +64,8 @@ $code($var($$(datadir$))/dbus-1/interfaces) so that other services can load
 them. Private APIs should not be installed There should be one file installed
 per D-Bus interface, named after the interface, containing a single top-level
 $code(<node>) element with a single $code(<interface>) beneath it. For example,
-interface $code(org.example.MyService1.Manager) would be described by file
-$file($var($$(datadir$))/dbus-1/interfaces/org.example.MyService1.Manager.xml):
+interface $code(com.example.MyService1.Manager) would be described by file
+$file($var($$(datadir$))/dbus-1/interfaces/com.example.MyService1.Manager.xml):
 
 [listing]
   [title]
@@ -77,7 +77,7 @@ $file($var($$(datadir$))/dbus-1/interfaces/org.example.MyService1.Manager.xml):
         "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
         "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd" >
     <node xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd">
-      <interface name="org.example.MyService1.InterestingInterface">
+      <interface name="com.example.MyService1.InterestingInterface">
         <method name="AddContact">
           <arg name="name" direction="in" type="s">
             <doc:doc><doc:summary>Name of new contact</doc:summary></doc:doc>
@@ -128,8 +128,8 @@ back from should be called using a generic D-Bus method invocation rather than
 a specific generated binding.)
 
 When API is broken, changed or removed, the service’s version number must be
-bumped; for example, from $code(org.example.MyService1)
-to $code(org.example.MyService2). If backwards compatibility is maintained in
+bumped; for example, from $code(com.example.MyService1)
+to $code(com.example.MyService2). If backwards compatibility is maintained in
 the service by implementing both the old and new interfaces, the service can
 own $em(both) well-known names and clients can use whichever they support.
 
@@ -140,21 +140,21 @@ Note, however, that supporting multiple interface versions simultaneously
 requires that $em(object paths) are versioned as well, so objects $em(must not)
 be put on the bus at the root path (‘/’). This is for technical reasons: signals
 sent from a D-Bus service have the originating service name overwritten by its
-unique name (e.g. $code(org.example.MyService2) is overwritten by $code(:1:15)).
+unique name (e.g. $code(com.example.MyService2) is overwritten by $code(:1:15)).
 If object paths are shared between objects implementing two versions of the
 service’s interface, client programs cannot tell which object a signal has come
 from. The solution is to include the version number in all object paths, for
-example $code(/org/example/MyService1/Manager) instead of $code(/) or
-$code(/org/example/MyService/Manager).
+example $code(/com/example/MyService1/Manager) instead of $code(/) or
+$code(/com/example/MyService/Manager).
 
 In summary, version numbers should be included in all service names, interface
 names and object paths:
 [list]
-* $code(org.example.MyService1)
-* $code(org.example.MyService1.InterestingInterface)
-* $code(org.example.MyService1.OtherInterface)
-* $code(/org/example/MyService1/Manager)
-* $code(/org/example/MyService1/OtherObject)
+* $code(com.example.MyService1)
+* $code(com.example.MyService1.InterestingInterface)
+* $code(com.example.MyService1.OtherInterface)
+* $code(/com/example/MyService1/Manager)
+* $code(/com/example/MyService1/OtherObject)
 
 == API design
    [id="api-design"]
@@ -188,7 +188,7 @@ needed by clients. This can be achieved by a combination of providing specific
 convenience APIs and designing APIs which operate on large data sets in a single
 call, rather than requiring as many calls as elements in the data set.
 
-Consider an address book API, $code(org.example.MyService1.AddressBook). It
+Consider an address book API, $code(com.example.MyService1.AddressBook). It
 might have an $code(AddContact(ss$) → (u$)) method to add a contact (taking name
 and e-mail address parameters and returning a unique contact ID), and a
 $code(RemoveContact(u$)) method to remove one by ID. In the normal case of
@@ -475,7 +475,7 @@ $code(Get$var(PropertyName)) and $code(Set$var(PropertyName)) methods.
 
 [example]
   For example, consider an object implementing an interface
-  $code(org.example.MyService1.SomeInterface) with methods:
+  $code(com.example.MyService1.SomeInterface) with methods:
   [list]
   * $code(GetName($) → (s$))
   * $code(SetName(s$) → ($))
@@ -518,7 +518,7 @@ not expose the entire file system hierarchy using $code(ObjectManager).
 
 [example]
   For example, consider an object implementing an interface
-  $code(org.example.MyService1.AddressBookManager) with methods:
+  $code(com.example.MyService1.AddressBookManager) with methods:
   [list]
   * $code(GetAddressBooks($) → (ao$))
   and signals:
@@ -527,9 +527,9 @@ not expose the entire file system hierarchy using $code(ObjectManager).
   * $code(AddressBookRemoved(o$))
 
   If the manager object is at path
-  $code(/org/example/MyService1/AddressBookManager), each address book is a
+  $code(/com/example/MyService1/AddressBookManager), each address book is a
   child object, e.g.
-  $code(/org/example/MyService1/AddressBookManager/SomeAddressBook).
+  $code(/com/example/MyService1/AddressBookManager/SomeAddressBook).
 
   The interface could be eliminated, and the
   $code(org.freedesktop.DBus.ObjectManager) interface implemented on the manager
@@ -547,6 +547,15 @@ All D-Bus names, from service names through to method parameters, follow a set
 of conventions. Following these conventions makes APIs more natural to use and
 consistent with all other services on the system.
 
+Services use reverse-domain-name notation, based on the domain name of the
+project providing the service (all in lower case), plus a unique name for the
+service (in camel case).
+
+[example]
+  For example, version 2 of an address book application called $code(ContactDex)
+  provided by a software vendor whose website is $code(chocolateteapot.com)
+  would use service name $code(com.chocolateteapot.ContactDex2).
+
 Almost all names use camel case with no underscores, as in the examples below.
 Method and signal parameters are an exception, using
 $code(lowercase_with_underscores). Type information is never encoded in the
@@ -556,21 +565,21 @@ $link[>>http://en.wikipedia.org/wiki/Hungarian_notation](Hungarian notation)).
 [example]
   [terms]
   - Service Name
-  * $code(org.example.MyService1)
+  * $code(com.example.MyService1)
   - Interface Name
-  * $code(org.example.MyService1.SomeInterface)
+  * $code(com.example.MyService1.SomeInterface)
   - Object Path (Root Object)
-  * $code(/org/example/MyService1)
+  * $code(/com/example/MyService1)
   - Object Path (Child Object)
-  * $code(/org/example/MyService1/SomeChild)
+  * $code(/com/example/MyService1/SomeChild)
   - Object Path (Grandchild Object)
-  * $code(/org/example/MyService1/AnotherChild/Grandchild1)
+  * $code(/com/example/MyService1/AnotherChild/Grandchild1)
   - Method Name
-  * $code(org.example.MyService1.SomeInterface.MethodName)
+  * $code(com.example.MyService1.SomeInterface.MethodName)
   - Signal Name
-  * $code(org.example.MyService1.SomeInterface.SignalName)
+  * $code(com.example.MyService1.SomeInterface.SignalName)
   - Property Name
-  * $code(org.example.MyService1.SomeInterface.PropertyName)
+  * $code(com.example.MyService1.SomeInterface.PropertyName)
 
 See also: $link[>#api-versioning].
 
@@ -789,8 +798,8 @@ $link[>>http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-star
 specification)).
 
 Service files must be named after the service’s well-known name, for example
-file $file(org.example.MyService1.service) for well-known name
-$code(org.example.MyService1). Files must be installed in
+file $file(com.example.MyService1.service) for well-known name
+$code(com.example.MyService1). Files must be installed in
 $file($var($$(datadir$))/dbus-1/services) for the session bus and
 $file($var($$(datadir$))/dbus-1/system-services) for the system bus. Note, however,
 that services on the system bus almost always need a
-- 
1.9.3