Improve documentation for Sphinx

Signed-off-by: Simon McVittie <smcv@collabora.com>

8 files changed, 63 insertions, 93 deletions

diff --git a/dbus_bindings/bytes.c b/dbus_bindings/bytes.c
index 26d6016..873a2fa 100644
--- a/dbus_bindings/bytes.c
+++ b/dbus_bindings/bytes.c
@@ -37,18 +37,18 @@
 #endif
 
 PyDoc_STRVAR(Byte_tp_doc,
+"dbus.Byte(integer or bytes of length 1[, variant_level])\n"
+"\n"
 "An unsigned byte: a subtype of int, with range restricted to [0, 255].\n"
 "\n"
-"A Byte b may be converted to a str of length 1 via str(b) == chr(b).\n"
+"A Byte `b` may be converted to a ``str`` of length 1 via\n"
+"``str(b) == chr(b)`` (Python 2) or to a ``bytes`` of length 1\n"
+"via ``bytes([b])`` (Python 3).\n"
 "\n"
 "Most of the time you don't want to use this class - it mainly exists\n"
 "for symmetry with the other D-Bus types. See `dbus.ByteArray` for a\n"
 "better way to handle arrays of Byte.\n"
 "\n"
-"Constructor::\n"
-"\n"
-"   dbus.Byte(integer or str of length 1[, variant_level])\n"
-"\n"
 ":py:attr:`variant_level` must be non-negative; the default is 0.\n"
 "\n"
 ".. py:attribute:: variant_level\n"
diff --git a/dbus_bindings/conn.c b/dbus_bindings/conn.c
index 9ef1487..739f305 100644
--- a/dbus_bindings/conn.c
+++ b/dbus_bindings/conn.c
@@ -31,11 +31,9 @@
 /* Connection definition ============================================ */
 
 PyDoc_STRVAR(Connection_tp_doc,
-"A D-Bus connection.\n"
-"\n"
-"::\n"
+"_dbus_bindings.Connection(address, mainloop=None)\n"
 "\n"
-"   Connection(address, mainloop=None) -> Connection\n"
+"A D-Bus connection.\n"
 );
 
 /* D-Bus Connection user data slot, containing an owned reference to either
diff --git a/dbus_bindings/containers.c b/dbus_bindings/containers.c
index 165f6fc..26f983b 100644
--- a/dbus_bindings/containers.c
+++ b/dbus_bindings/containers.c
@@ -33,6 +33,8 @@
 /* Array ============================================================ */
 
 PyDoc_STRVAR(Array_tp_doc,
+"dbus.Array([iterable][, signature][, variant_level])\n"
+"\n"
 "An array of similar items, implemented as a subtype of list.\n"
 "\n"
 "As currently implemented, an Array behaves just like a list, but\n"
@@ -40,10 +42,6 @@ PyDoc_STRVAR(Array_tp_doc,
 "conversion of its items to D-Bus types is only done when it's sent in\n"
 "a Message. This might change in future so validation is done earlier.\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    dbus.Array([iterable][, signature][, variant_level])\n"
-"\n"
 ":py:attr:`variant_level` must be non-negative; the default is 0.\n"
 "\n"
 "``signature`` is the D-Bus signature string for a single element of the\n"
@@ -261,6 +259,8 @@ PyTypeObject DBusPyArray_Type = {
 /* Dict ============================================================= */
 
 PyDoc_STRVAR(Dict_tp_doc,
+"dbus.Dictionary(mapping_or_iterable=(), signature=None, variant_level=0)\n"
+"\n"
 "An mapping whose keys are similar and whose values are similar,\n"
 "implemented as a subtype of dict.\n"
 "\n"
@@ -269,10 +269,6 @@ PyDoc_STRVAR(Dict_tp_doc,
 "conversion of its items to D-Bus types is only done when it's sent in\n"
 "a Message. This may change in future so validation is done earlier.\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    Dictionary(mapping_or_iterable=(), signature=None, variant_level=0)\n"
-"\n"
 ":py:attr:`variant_level` must be non-negative; the default is 0.\n"
 "\n"
 "``signature`` is either a string or None. If a string, it must consist\n"
@@ -516,11 +512,9 @@ PyTypeObject DBusPyDict_Type = {
 static PyObject *struct_signatures;
 
 PyDoc_STRVAR(Struct_tp_doc,
-"An structure containing items of possibly distinct types.\n"
+"dbus.Struct(iterable, signature=None, variant_level=0)\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    dbus.Struct(iterable, signature=None, variant_level=0) -> Struct\n"
+"An structure containing items of possibly distinct types.\n"
 "\n"
 "D-Bus structs may not be empty, so the iterable argument is required and\n"
 "may not be an empty iterable.\n"
diff --git a/dbus_bindings/int.c b/dbus_bindings/int.c
index 871a065..109d4c7 100644
--- a/dbus_bindings/int.c
+++ b/dbus_bindings/int.c
@@ -29,8 +29,10 @@
 
 #ifdef PY3
 #define INTBASE (DBusPyLongBase_Type)
+#define LONG_TYPE_NAME "int"
 #else
 #define INTBASE (DBusPyIntBase_Type)
+#define LONG_TYPE_NAME "long"
 #endif
 
 /* Specific types =================================================== */
@@ -38,12 +40,10 @@
 /* Boolean, a subclass of DBusPythonInt ============================= */
 
 PyDoc_STRVAR(Boolean_tp_doc,
-"A boolean, represented as a subtype of `int` (not `bool`, because `bool`\n"
-"cannot be subclassed).\n"
-"\n"
-"Constructor::\n"
+"dbus.Boolean(value: bool[, variant_level: int])\n"
 "\n"
-"    dbus.Boolean(value[, variant_level]) -> Boolean\n"
+"A boolean, represented as a subtype of ``int`` (not ``bool``, because ``bool``\n"
+"cannot be subclassed).\n"
 "\n"
 "``value`` is converted to 0 or 1 as if by ``int(bool(value))``.\n"
 "\n"
@@ -148,13 +148,11 @@ PyTypeObject DBusPyBoolean_Type = {
 /* Int16 ============================================================ */
 
 PyDoc_STRVAR(Int16_tp_doc,
+"dbus.Int16(value: int[, variant_level: int])\n"
+"\n"
 "A signed 16-bit integer between -0x8000 and +0x7FFF, represented as\n"
 "a subtype of `int`.\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    dbus.Int16(value: int[, variant_level: int]) -> Int16\n"
-"\n"
 "value must be within the allowed range, or OverflowError will be\n"
 "raised.\n"
 "\n"
@@ -238,12 +236,10 @@ PyTypeObject DBusPyInt16_Type = {
 /* UInt16 =========================================================== */
 
 PyDoc_STRVAR(UInt16_tp_doc,
-"An unsigned 16-bit integer between 0 and 0xFFFF, represented as\n"
-"a subtype of `int`.\n"
-"\n"
-"Constructor::\n"
+"dbus.UInt16(value: int[, variant_level: int])\n"
 "\n"
-"    dbus.UInt16(value: int[, variant_level: int]) -> UInt16\n"
+"An unsigned 16-bit integer between 0 and 0xFFFF, represented as\n"
+"a subtype of ``int``.\n"
 "\n"
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
@@ -330,12 +326,10 @@ PyTypeObject DBusPyUInt16_Type = {
 /* Int32 ============================================================ */
 
 PyDoc_STRVAR(Int32_tp_doc,
-"A signed 32-bit integer between -0x8000 0000 and +0x7FFF FFFF, represented as\n"
-"a subtype of `int`.\n"
-"\n"
-"Constructor::\n"
+"dbus.Int32(value: int[, variant_level: int])\n"
 "\n"
-"    dbus.Int32(value: int[, variant_level: int]) -> Int32\n"
+"A signed 32-bit integer between -0x8000 0000 and +0x7FFF FFFF, represented as\n"
+"a subtype of ``int``.\n"
 "\n"
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
@@ -420,15 +414,10 @@ PyTypeObject DBusPyInt32_Type = {
 /* UInt32 =========================================================== */
 
 PyDoc_STRVAR(UInt32_tp_doc,
-"An unsigned 32-bit integer between 0 and 0xFFFF FFFF, represented as a\n"
-"subtype of `long`.\n"
-"\n"
-"Note that this may be changed in future to be a subtype of `int` on\n"
-"64-bit platforms; applications should not rely on either behaviour.\n"
+"dbus.UInt32(value: " LONG_TYPE_NAME "[, variant_level: int])\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    dbus.UInt32(value: long[, variant_level: int]) -> UInt32\n"
+"An unsigned 32-bit integer between 0 and 0xFFFF FFFF, represented as a\n"
+"subtype of ``long`` in Python 2 or ``int`` in Python 3.\n"
 "\n"
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
@@ -521,19 +510,15 @@ PyTypeObject DBusPyUInt32_Type = {
 /* Int64 =========================================================== */
 
 PyDoc_STRVAR(Int64_tp_doc,
+"dbus.Int64(value: " LONG_TYPE_NAME "[, variant_level: int])\n"
+"\n"
 "A signed 64-bit integer between -0x8000 0000 0000 0000 and\n"
-"+0x7FFF FFFF FFFF FFFF, represented as a subtype of `long`.\n"
+"+0x7FFF FFFF FFFF FFFF, represented as a\n"
+"subtype of ``long`` in Python 2 or ``int`` in Python 3.\n"
 "\n"
 "Note that this may be changed in future to be a subtype of `int` on\n"
 "64-bit platforms; applications should not rely on either behaviour.\n"
 "\n"
-"This type only works on platforms where the C compiler has suitable\n"
-"64-bit types, such as C99 ``long long``.\n"
-"\n"
-"Constructor::\n"
-"\n"
-"    dbus.Int64(value: long[, variant_level: int]) -> Int64\n"
-"\n"
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
 "\n"
@@ -631,15 +616,10 @@ PyTypeObject DBusPyInt64_Type = {
 /* UInt64 =========================================================== */
 
 PyDoc_STRVAR(UInt64_tp_doc,
-"An unsigned 64-bit integer between 0 and 0xFFFF FFFF FFFF FFFF,\n"
-"represented as a subtype of `long`.\n"
+"dbus.UInt64(value: " LONG_TYPE_NAME "[, variant_level: int])\n"
 "\n"
-"This type only exists on platforms where the C compiler has suitable\n"
-"64-bit types, such as C99 ``unsigned long long``.\n"
-"\n"
-"Constructor::\n"
-"\n"
-"    dbus.UInt64(value: long[, variant_level: int]) -> UInt64\n"
+"An unsigned 64-bit integer between 0 and 0xFFFF FFFF FFFF FFFF,\n"
+"subtype of ``long`` in Python 2 or ``int`` in Python 3.\n"
 "\n"
 "``value`` must be within the allowed range, or `OverflowError` will be\n"
 "raised.\n"
diff --git a/dbus_bindings/message.c b/dbus_bindings/message.c
index ded8fe1..43b8df6 100644
--- a/dbus_bindings/message.c
+++ b/dbus_bindings/message.c
@@ -93,12 +93,11 @@ MethodCallMessage_tp_repr(PyObject *self)
         path, interface, member, destination);
 }
 
-PyDoc_STRVAR(MethodCallMessage_tp_doc, "A method-call message.\n"
+PyDoc_STRVAR(MethodCallMessage_tp_doc,
+"dbus.lowlevel.MethodCallMessage(destination: str or None, path: str, "
+"interface: str or None, method: str)\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    dbus.lowlevel.MethodCallMessage(destination: str or None, path: str,\n"
-"                                    interface: str or None, method: str)\n"
+"A method-call message.\n"
 "\n"
 "``destination`` is the destination bus name, or None to send the\n"
 "message directly to the peer (usually the bus daemon).\n"
@@ -139,9 +138,10 @@ MethodCallMessage_tp_init(Message *self, PyObject *args, PyObject *kwargs)
     return 0;
 }
 
-PyDoc_STRVAR(MethodReturnMessage_tp_doc, "A method-return message.\n\n"
-"Constructor::\n\n"
-"    dbus.lowlevel.MethodReturnMessage(method_call: MethodCallMessage)\n");
+PyDoc_STRVAR(MethodReturnMessage_tp_doc,
+"dbus.lowlevel.MethodReturnMessage(method_call: MethodCallMessage)\n"
+"\n"
+"A method-return message.");
 
 static int
 MethodReturnMessage_tp_init(Message *self, PyObject *args, PyObject *kwargs)
@@ -165,9 +165,10 @@ MethodReturnMessage_tp_init(Message *self, PyObject *args, PyObject *kwargs)
     return 0;
 }
 
-PyDoc_STRVAR(SignalMessage_tp_doc, "A signal message.\n\n"
-"Constructor::\n\n"
-"   dbus.lowlevel.SignalMessage(path: str, interface: str, method: str)\n");
+PyDoc_STRVAR(SignalMessage_tp_doc,
+"dbus.lowlevel.SignalMessage(path: str, interface: str, method: str)\n"
+"\n"
+"A signal message.\n");
 static int
 SignalMessage_tp_init(Message *self, PyObject *args, PyObject *kwargs)
 {
@@ -216,10 +217,11 @@ SignalMessage_tp_repr(PyObject *self)
                                 path, interface, member, destination);
 }
 
-PyDoc_STRVAR(ErrorMessage_tp_doc, "An error message.\n\n"
-"Constructor::\n\n"
-"   dbus.lowlevel.ErrorMessage(reply_to: Message, error_name: str,\n"
-"                              error_message: str or None)\n");
+PyDoc_STRVAR(ErrorMessage_tp_doc,
+"dbus.lowlevel.ErrorMessage(reply_to: Message, error_name: str, "
+"error_message: str or None)\n"
+"\n"
+"An error message.\n");
 static int
 ErrorMessage_tp_init(Message *self, PyObject *args, PyObject *kwargs)
 {
diff --git a/dbus_bindings/signature.c b/dbus_bindings/signature.c
index 574968b..c1a32e7 100644
--- a/dbus_bindings/signature.c
+++ b/dbus_bindings/signature.c
@@ -31,14 +31,12 @@
 #include "types-internal.h"
 
 PyDoc_STRVAR(Signature_tp_doc,
+"Signature(value: str or unicode[, variant_level: int])\n"
+"\n"
 "A string subclass whose values are restricted to valid D-Bus\n"
 "signatures. When iterated over, instead of individual characters it\n"
 "produces Signature instances representing single complete types.\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    ``Signature(value: str or unicode[, variant_level: int]) -> Signature``\n"
-"\n"
 "``value`` must be a valid D-Bus signature (zero or more single complete\n"
 "types).\n"
 "\n"
diff --git a/dbus_bindings/string.c b/dbus_bindings/string.c
index 8d34b4d..ce8f03d 100644
--- a/dbus_bindings/string.c
+++ b/dbus_bindings/string.c
@@ -203,21 +203,21 @@ PyTypeObject DBusPyObjectPath_Type = {
 /* Unicode string representation ==================================== */
 
 PyDoc_STRVAR(String_tp_doc,
-"A string represented using Unicode - a subtype of `unicode`.\n"
+"dbus.String(value: str or unicode[, variant_level: int])\n"
+"\n"
+"A string represented using Unicode - a subtype of ``unicode`` (Python 2)\n"
+"or ``str`` (Python 3).\n"
 "\n"
 "All strings on D-Bus are required to be valid Unicode; in the \"wire\n"
 "protocol\" they're transported as UTF-8.\n"
 "\n"
 "By default, when strings are converted from D-Bus to Python, they\n"
-"come out as this class. If you prefer to get UTF-8 strings (as instances\n"
+"come out as this class. In Python 2, if you prefer to get UTF-8 strings\n"
+"(as instances\n"
 "of a subtype of `str`) or you want to avoid the conversion overhead of\n"
 "going from UTF-8 to Python's internal Unicode representation, see the\n"
 "documentation for `dbus.UTF8String`.\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    String(value: str or unicode[, variant_level: int]) -> String\n"
-"\n"
 "variant_level must be non-negative; the default is 0.\n"
 );
 
diff --git a/dbus_bindings/unixfd.c b/dbus_bindings/unixfd.c
index 62a5acb..ecb32d2 100644
--- a/dbus_bindings/unixfd.c
+++ b/dbus_bindings/unixfd.c
@@ -29,11 +29,9 @@
 #include "types-internal.h"
 
 PyDoc_STRVAR(UnixFd_tp_doc,
-"An Unix Fd.\n"
+"dbus.UnixFd(value: int or file object[, variant_level: int])\n"
 "\n"
-"Constructor::\n"
-"\n"
-"    dbus.UnixFd(value: int or file object[, variant_level: int]) -> UnixFd\n"
+"A Unix Fd.\n"
 "\n"
 "``value`` must be the integer value of a file descriptor, or an object that\n"
 "implements the fileno() method. Otherwise, `ValueError` will be\n"