Improve docstrings for String and UTF8String explaining how to get UTF8String from the API.

1 files changed, 26 insertions, 0 deletions

diff --git a/_dbus_bindings/string.c b/_dbus_bindings/string.c
index 28e69c4..7557007 100644
--- a/_dbus_bindings/string.c
+++ b/_dbus_bindings/string.c
@@ -29,6 +29,23 @@
 PyDoc_STRVAR(UTF8String_tp_doc,
 "A string represented using UTF-8 - a subtype of `str`.\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 byte arrays are converted from D-Bus to Python, they\n"
+"come out as a `dbus.String`, which is a subtype of `unicode`.\n"
+"If you prefer to get UTF-8 strings (as instances of this class) or you\n"
+"want to avoid the conversion overhead of going from UTF-8 to Python's\n"
+"internal Unicode representation, you can pass the ``utf8_strings=True``\n"
+"keyword argument to any of these methods:\n"
+"\n"
+"* any D-Bus method proxy, or ``connect_to_signal``, on the objects returned\n"
+"  by `Bus.get_object` and `Bus.get_object_by_unique_name`\n"
+"* any D-Bus method on a `dbus.Interface`\n"
+"* `dbus.Interface.connect_to_signal`\n"
+"* `Bus.add_signal_receiver`\n"
+"\n"
+"\n"
 "Constructor::\n"
 "\n"
 "    dbus.UTF8String(value: str or unicode[, variant_level: int]) -> UTF8String\n"
@@ -188,6 +205,15 @@ PyTypeObject DBusPyObjectPath_Type = {
 PyDoc_STRVAR(String_tp_doc,
 "A string represented using Unicode - a subtype of `unicode`.\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"
+"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"