Improve API documentation markup, particularly adding :Since: annotations

5 files changed, 88 insertions, 30 deletions

diff --git a/dbus/bus.py b/dbus/bus.py
index da56a32..72d3958 100644
--- a/dbus/bus.py
+++ b/dbus/bus.py
@@ -29,7 +29,17 @@ from _dbus_bindings import validate_interface_name, validate_member_name,\
                            DBUS_START_REPLY_SUCCESS, \
                            DBUS_START_REPLY_ALREADY_RUNNING, \
                            BUS_DAEMON_NAME, BUS_DAEMON_PATH, BUS_DAEMON_IFACE,\
-                           HANDLER_RESULT_NOT_YET_HANDLED
+                           HANDLER_RESULT_NOT_YET_HANDLED, \
+                           NAME_FLAG_ALLOW_REPLACEMENT, \
+                           NAME_FLAG_DO_NOT_QUEUE, \
+                           NAME_FLAG_REPLACE_EXISTING, \
+                           RELEASE_NAME_REPLY_NON_EXISTENT, \
+                           RELEASE_NAME_REPLY_NOT_OWNER, \
+                           RELEASE_NAME_REPLY_RELEASED, \
+                           REQUEST_NAME_REPLY_ALREADY_OWNER, \
+                           REQUEST_NAME_REPLY_EXISTS, \
+                           REQUEST_NAME_REPLY_IN_QUEUE, \
+                           REQUEST_NAME_REPLY_PRIMARY_OWNER
 from dbus.connection import Connection
 from dbus.exceptions import DBusException
 
@@ -90,6 +100,8 @@ class NameOwnerWatch(object):
 class BusConnection(Connection):
     """A connection to a D-Bus daemon that implements the
     ``org.freedesktop.DBus`` pseudo-service.
+
+    :Since: 0.81.0
     """
 
     TYPE_SESSION    = BUS_SESSION
@@ -234,6 +246,7 @@ class BusConnection(Connection):
             `bus_name` : str
                 A bus name, either unique or well-known
         :Returns: a `dbus.UInt32`
+        :Since: 0.80.0
         """
         validate_bus_name(bus_name)
         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
@@ -254,7 +267,8 @@ class BusConnection(Connection):
             second is either START_REPLY_SUCCESS or
             START_REPLY_ALREADY_RUNNING.
 
-        :Raises DBusException: if the service could not be started.
+        :Raises `DBusException`: if the service could not be started.
+        :Since: 0.80.0
         """
         validate_bus_name(bus_name)
         return (True, self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
@@ -272,14 +286,14 @@ class BusConnection(Connection):
                 The well-known name to be requested
             `flags` : dbus.UInt32
                 A bitwise-OR of 0 or more of the flags
-                `DBUS_NAME_FLAG_ALLOW_REPLACEMENT`,
-                `DBUS_NAME_FLAG_REPLACE_EXISTING`
-                and `DBUS_NAME_FLAG_DO_NOT_QUEUE`
-        :Returns: `DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER`,
-            `DBUS_REQUEST_NAME_REPLY_IN_QUEUE`,
-            `DBUS_REQUEST_NAME_REPLY_EXISTS` or
-            `DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER`
-        :Raises DBusException: if the bus daemon cannot be contacted or
+                `NAME_FLAG_ALLOW_REPLACEMENT`,
+                `NAME_FLAG_REPLACE_EXISTING`
+                and `NAME_FLAG_DO_NOT_QUEUE`
+        :Returns: `REQUEST_NAME_REPLY_PRIMARY_OWNER`,
+            `REQUEST_NAME_REPLY_IN_QUEUE`,
+            `REQUEST_NAME_REPLY_EXISTS` or
+            `REQUEST_NAME_REPLY_ALREADY_OWNER`
+        :Raises `DBusException`: if the bus daemon cannot be contacted or
             returns an error.
         """
         validate_bus_name(name, allow_unique=False)
@@ -293,10 +307,10 @@ class BusConnection(Connection):
         :Parameters:
             `name` : str
                 The well-known name to be released
-        :Returns: `DBUS_RELEASE_NAME_REPLY_RELEASED`,
-            `DBUS_RELEASE_NAME_REPLY_NON_EXISTENT`
-            or `DBUS_RELEASE_NAME_REPLY_NOT_OWNER`
-        :Raises DBusException: if the bus daemon cannot be contacted or
+        :Returns: `RELEASE_NAME_REPLY_RELEASED`,
+            `RELEASE_NAME_REPLY_NON_EXISTENT`
+            or `RELEASE_NAME_REPLY_NOT_OWNER`
+        :Raises `DBusException`: if the bus daemon cannot be contacted or
             returns an error.
         """
         validate_bus_name(name, allow_unique=False)
@@ -308,6 +322,7 @@ class BusConnection(Connection):
         """Return a list of all currently-owned names on the bus.
 
         :Returns: a dbus.Array of dbus.UTF8String
+        :Since: 0.81.0
         """
         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
                                   BUS_DAEMON_IFACE, 'ListNames',
@@ -317,6 +332,7 @@ class BusConnection(Connection):
         """Return a list of all names that can be activated on the bus.
 
         :Returns: a dbus.Array of dbus.UTF8String
+        :Since: 0.81.0
         """
         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
                                   BUS_DAEMON_IFACE, 'ListNames',
@@ -326,7 +342,8 @@ class BusConnection(Connection):
         """Return the unique connection name of the primary owner of the
         given name.
 
-        :Raises DBusException: if the `bus_name` has no owner
+        :Raises `DBusException`: if the `bus_name` has no owner
+        :Since: 0.81.0
         """
         validate_bus_name(bus_name, allow_unique=False)
         return self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
@@ -340,6 +357,8 @@ class BusConnection(Connection):
         `callback` will be called with one argument, which is either the
         unique connection name, or the empty string (meaning the name is
         not owned).
+
+        :Since: 0.81.0
         """
         return NameOwnerWatch(self, bus_name, callback)
 
@@ -347,7 +366,7 @@ class BusConnection(Connection):
         """Return True iff the given bus name has an owner on this bus.
 
         :Parameters:
-            `name` : str
+            `bus_name` : str
                 The bus name to look up
         :Returns: a `bool`
         """
@@ -362,7 +381,8 @@ class BusConnection(Connection):
         :Parameters:
             `rule` : str
                 The match rule
-        :Raises: `DBusException` on error.
+        :Raises `DBusException`: on error.
+        :Since: 0.80.0
         """
         self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
                            BUS_DAEMON_IFACE, 'AddMatch', 's', (rule,))
@@ -378,7 +398,8 @@ class BusConnection(Connection):
         :Parameters:
             `rule` : str
                 The match rule
-        :Raises: `DBusException` on error.
+        :Raises `DBusException`: on error.
+        :Since: 0.80.0
         """
         self.call_async(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
                         BUS_DAEMON_IFACE, 'AddMatch', 's', (rule,),
@@ -391,7 +412,8 @@ class BusConnection(Connection):
         :Parameters:
             `rule` : str
                 The match rule
-        :Raises: `DBusException` on error.
+        :Raises `DBusException`: on error.
+        :Since: 0.80.0
         """
         self.call_blocking(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
                            BUS_DAEMON_IFACE, 'RemoveMatch', 's', (rule,))
@@ -405,7 +427,8 @@ class BusConnection(Connection):
         :Parameters:
             `rule` : str
                 The match rule
-        :Raises: `DBusException` on error.
+        :Raises `DBusException`: on error.
+        :Since: 0.80.0
         """
         self.call_async(BUS_DAEMON_NAME, BUS_DAEMON_PATH,
                         BUS_DAEMON_IFACE, 'RemoveMatch', 's', (rule,),
diff --git a/dbus/connection.py b/dbus/connection.py
index 78ed287..6931d9b 100644
--- a/dbus/connection.py
+++ b/dbus/connection.py
@@ -228,6 +228,8 @@ class SignalMatch(object):
 class Connection(_Connection):
     """A connection to another application. In this base class there is
     assumed to be no bus daemon.
+
+    :Since: 0.81.0
     """
 
     ProxyObjectClass = ProxyObject
@@ -261,6 +263,7 @@ class Connection(_Connection):
             does not exist.
         :Raises DBusException: if the implementation has failed
             to activate the given bus name.
+        :Since: 0.81.0
         """
         return bus_name
 
@@ -514,6 +517,7 @@ class Connection(_Connection):
         are None, the implementation may request that no reply is sent.
 
         :Returns: The dbus.lowlevel.PendingCall.
+        :Since: 0.81.0
         """
         if object_path == LOCAL_PATH:
             raise DBusException('Methods may not be called on the reserved '
@@ -567,6 +571,7 @@ class Connection(_Connection):
                       signature, args, timeout=-1.0, utf8_strings=False,
                       byte_arrays=False):
         """Call the given method, synchronously.
+        :Since: 0.81.0
         """
         if object_path == LOCAL_PATH:
             raise DBusException('Methods may not be called on the reserved '
diff --git a/dbus/decorators.py b/dbus/decorators.py
index 892a11f..37b62ef 100644
--- a/dbus/decorators.py
+++ b/dbus/decorators.py
@@ -86,22 +86,30 @@ def method(dbus_interface, in_signature=None, out_signature=None,
             case of "fallback paths" you'll usually want to use the object
             path in the method's implementation.
 
+            :Since: 0.80.0?
+
         `destination_keyword` : str or None
             If not None (the default), the decorated method will receive
             the destination bus name as a keyword argument with this name.
             Included for completeness - you shouldn't need this.
 
+            :Since: 0.80.0?
+
         `message_keyword` : str or None
             If not None (the default), the decorated method will receive
             the `dbus.lowlevel.MethodCallMessage` as a keyword argument
             with this name.
 
+            :Since: 0.80.0?
+
         `connection_keyword` : str or None
             If not None (the default), the decorated method will receive
             the `dbus.connection.Connection` as a keyword argument
             with this name. This is generally only useful for objects
             that are available on more than one connection.
 
+            :Since: 0.82.0
+
         `utf8_strings` : bool
             If False (default), D-Bus strings are passed to the decorated
             method as objects of class dbus.String, a unicode subclass.
@@ -113,6 +121,8 @@ def method(dbus_interface, in_signature=None, out_signature=None,
             This option does not affect object-paths and signatures, which
             are always 8-bit strings (str subclass) encoded in ASCII.
 
+            :Since: 0.80.0
+
         `byte_arrays` : bool
             If False (default), a byte array will be passed to the decorated
             method as an `Array` (a list subclass) of `Byte` objects.
@@ -121,6 +131,8 @@ def method(dbus_interface, in_signature=None, out_signature=None,
             a `ByteArray`, a str subclass. This is usually what you want,
             but is switched off by default to keep dbus-python's API
             consistent.
+
+            :Since: 0.80.0
     """
     _dbus_bindings.validate_interface_name(dbus_interface)
 
@@ -221,6 +233,8 @@ def signal(dbus_interface, signature=None, path_keyword=None,
             /def and /x/y/z on connection 2, and the keyword argument is
             /foo, then signals will be emitted from /abc/foo and /def/foo
             on connection 1, and /x/y/z/foo on connection 2.
+
+            :Since: 0.82.0
     """
     _dbus_bindings.validate_interface_name(dbus_interface)
 
diff --git a/dbus/proxies.py b/dbus/proxies.py
index 440a5d5..452a64a 100644
--- a/dbus/proxies.py
+++ b/dbus/proxies.py
@@ -181,7 +181,7 @@ class ProxyObject(object):
             `bus_name` : str
                 A bus name for the application owning the object, to be used
                 as the destination for method calls and the sender for
-                signal matches. The keyword argument `named_service` is a
+                signal matches. The keyword argument ``named_service`` is a
                 deprecated alias for this.
             `object_path` : str
                 The object path at which the application exports the object
@@ -261,13 +261,13 @@ class ProxyObject(object):
             is that unique name.
 
             If the proxy was instantiated with a well-known name and with
-            `follow_name_owner_changes` set false (the default), this
+            ``follow_name_owner_changes`` set false (the default), this
             property is the unique name of the connection that owned that
             well-known name when the proxy was instantiated, which might
             not actually own the requested well-known name any more.
 
             If the proxy was instantiated with a well-known name and with
-            `follow_name_owner_changes` set true, this property is that
+            ``follow_name_owner_changes`` set true, this property is that
             well-known name.
             """)
 
diff --git a/dbus/service.py b/dbus/service.py
index f871556..d7b3a74 100644
--- a/dbus/service.py
+++ b/dbus/service.py
@@ -459,6 +459,8 @@ class Object(Interface):
         """The object-path at which this object is available.
         Access raises AttributeError if there is no object path, or more than
         one object path.
+
+        Changed in 0.82.0: AttributeError can be raised.
         """
         if self._object_path is _MANY:
             raise AttributeError('Object %r has more than one object path: '
@@ -473,6 +475,8 @@ class Object(Interface):
         """The Connection on which this object is available.
         Access raises AttributeError if there is no Connection, or more than
         one Connection.
+
+        Changed in 0.82.0: AttributeError can be raised.
         """
         if self._connection is _MANY:
             raise AttributeError('Object %r is on more than one Connection: '
@@ -491,6 +495,8 @@ class Object(Interface):
         versions of dbus-python, so do not rely on their exact length.
         The first two items are the dbus.connection.Connection and the object
         path.
+
+        :Since: 0.82.0
         """
         return iter(self._locations)
 
@@ -512,8 +518,10 @@ class Object(Interface):
                 can only be made available at one object path; if the class
                 attribute is set True by a subclass, the object can be made
                 available with more than one object path.
+
         :Raises ValueError: if the object's class attributes do not allow the
             object to be exported in the desired way.
+        :Since: 0.82.0
         """
         if path == LOCAL_PATH:
             raise ValueError('Objects may not be exported on the reserved '
@@ -570,6 +578,7 @@ class Object(Interface):
         :Raises LookupError:
             if the object was not exported on the requested connection
             or path, or (if both are None) was not exported at all.
+        :Since: 0.81.1
         """
         self._locations_lock.acquire()
         try:
@@ -731,7 +740,10 @@ class Object(Interface):
 
 class FallbackObject(Object):
     """An object that implements an entire subtree of the object-path
-    tree."""
+    tree.
+
+    :Since: 0.82.0
+    """
 
     SUPPORTS_MULTIPLE_OBJECT_PATHS = True
 
@@ -743,15 +755,16 @@ class FallbackObject(Object):
 
         :Parameters:
             `conn` : dbus.connection.Connection or None
-                The connection on which to export this object.
+                The connection on which to export this object. If this is not
+                None, an `object_path` must also be provided.
 
                 If None, the object is not initially available on any
                 Connection.
 
             `object_path` : str or None
                 A D-Bus object path at which to make this Object available
-                immediately. If this is not None, a `conn` or `bus_name` must
-                also be provided.
+                immediately. If this is not None, a `conn` must also be
+                provided.
 
                 This object will implements all object-paths in the subtree
                 starting at this object-path, except where a more specific
@@ -760,7 +773,10 @@ class FallbackObject(Object):
         super(FallbackObject, self).__init__()
         self._fallback = True
 
-        if conn is None and object_path is not None:
-            raise TypeError('If object_path is given, conn is required')
-        if conn is not None and object_path is not None:
+        if conn is None:
+            if object_path is not None:
+                raise TypeError('If object_path is given, conn is required')
+        elif object_path is None:
+            raise TypeError('If conn is given, object_path is required')
+        else:
             self.add_to_connection(conn, object_path)