From b81df570c8e7a450cfcbd09663f2f15725906b7a Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Wed, 2 May 2018 12:05:30 +0100 Subject: Improve documentation for Sphinx Signed-off-by: Simon McVittie --- dbus_bindings/bytes.c | 10 +++---- dbus_bindings/conn.c | 6 ++--- dbus_bindings/containers.c | 18 +++++-------- dbus_bindings/int.c | 66 ++++++++++++++++------------------------------ dbus_bindings/message.c | 32 +++++++++++----------- dbus_bindings/signature.c | 6 ++--- dbus_bindings/string.c | 12 ++++----- dbus_bindings/unixfd.c | 6 ++--- 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" -- cgit v1.2.1