Improve Python documentation

1 files changed, 49 insertions, 32 deletions

diff --git a/bindings/python/lilv.py b/bindings/python/lilv.py
index edfc639..024bfe7 100644
--- a/bindings/python/lilv.py
+++ b/bindings/python/lilv.py
@@ -278,12 +278,11 @@ class Plugin(Structure):
 
         This returns the URI of the bundle where the plugin itself was found.  Note
         that the data for a plugin may be spread over many bundles, that is,
-        lilv_plugin_get_data_uris() may return URIs which are not within this
-        bundle.
+        get_data_uris() may return URIs which are not within this bundle.
 
         Typical hosts should not need to use this function.
         Note this always returns a fully qualified URI.  If you want a local
-        filesystem path, use lilv_file_uri_parse().
+        filesystem path, use lilv.file_uri_parse().
         """
         return Node.wrap(node_duplicate(plugin_get_bundle_uri(self.plugin)))
 
@@ -292,7 +291,7 @@ class Plugin(Structure):
 
         Typical hosts should not need to use this function.
         Note this always returns fully qualified URIs.  If you want local
-        filesystem paths, use lilv_file_uri_parse().
+        filesystem paths, use lilv.file_uri_parse().
         """
         return Nodes(plugin_get_data_uris(self.plugin))
 
@@ -300,7 +299,7 @@ class Plugin(Structure):
         """Get the (resolvable) URI of the shared library for `plugin`.
 
         Note this always returns a fully qualified URI.  If you want a local
-        filesystem path, use lilv_file_uri_parse().
+        filesystem path, use lilv.file_uri_parse().
         """
         return Node.wrap(node_duplicate(plugin_get_library_uri(self.plugin)))
 
@@ -345,8 +344,8 @@ class Plugin(Structure):
         A feature is "supported" by a plugin if it is required OR optional.
 
         Since required features have special rules the host must obey, this function
-        probably shouldn't be used by normal hosts.  Using lilv_plugin_get_optional_features()
-        and lilv_plugin_get_required_features() separately is best in most cases.
+        probably shouldn't be used by normal hosts.  Using get_optional_features()
+        and get_required_features() separately is best in most cases.
         """
         return Nodes(plugin_get_supported_features(self.plugin))
 
@@ -378,7 +377,7 @@ class Plugin(Structure):
     def get_extension_data(self):
         """Get a sequence of all extension data provided by a plugin.
 
-        This can be used to find which URIs lilv_instance_get_extension_data()
+        This can be used to find which URIs get_extension_data()
         will return a value for without instantiating the plugin.
         """
         return Nodes(plugin_get_extension_data(self.plugin))
@@ -391,7 +390,7 @@ class Plugin(Structure):
     #     """Get the port ranges (minimum, maximum and default values) for all ports.
 
     #     `min_values`, `max_values` and `def_values` must either point to an array
-    #     of N floats, where N is the value returned by lilv_plugin_get_num_ports()
+    #     of N floats, where N is the value returned by get_num_ports()
     #     for this plugin, or None.  The elements of the array will be set to the
     #     the minimum, maximum and default values of the ports on this plugin,
     #     with array index corresponding to port index.  If a port doesn't have a
@@ -400,7 +399,7 @@ class Plugin(Structure):
 
     #     This is a convenience method for the common case of getting the range of
     #     all float ports on a plugin, and may be significantly faster than
-    #     repeated calls to lilv_port_get_range().
+    #     repeated calls to Port.get_range().
     #     """
     #     plugin_get_port_ranges_float(self.plugin, min_values, max_values, def_values)
 
@@ -414,7 +413,7 @@ class Plugin(Structure):
         """Return whether or not the plugin introduces (and reports) latency.
 
         The index of the latency port can be found with
-        lilv_plugin_get_latency_port() ONLY if this function returns true.
+        get_latency_port() ONLY if this function returns true.
         """
         return plugin_has_latency(self.plugin)
 
@@ -443,7 +442,7 @@ class Plugin(Structure):
     def get_port_by_symbol(self, symbol):
         """Get a port on `plugin` by `symbol`.
 
-        Note this function is slower than lilv_plugin_get_port_by_index(),
+        Note this function is slower than get_port_by_index(),
         especially on plugins with a very large number of ports.
         """
         if type(symbol) == str:
@@ -468,7 +467,7 @@ class Plugin(Structure):
     def get_project(self):
         """Get the project the plugin is a part of.
 
-        More information about the project can be read via lilv_world_find_nodes(),
+        More information about the project can be read via find_nodes(),
         typically using properties from DOAP (e.g. doap:name).
         """
         return Node.wrap(plugin_get_project(self.plugin))
@@ -565,7 +564,7 @@ class Port(Structure):
         return Node.wrap(node_duplicate(port_get_node(self.plugin, self.port)))
 
     def get_value(self, predicate):
-        """Port analog of lilv_plugin_get_value()."""
+        """Port analog of Plugin.get_value()."""
         return Nodes(port_get_value(self.plugin.plugin, self.port, predicate.node))
 
     def get(self, predicate):
@@ -620,7 +619,7 @@ class Port(Structure):
         """Get all the classes of a port.
 
         This can be used to determine if a port is an input, output, audio,
-        control, midi, etc, etc, though it's simpler to use lilv_port_is_a().
+        control, midi, etc, etc, though it's simpler to use is_a().
         The returned list does not include lv2:Port, which is implied.
         Returned value is shared and must not be destroyed by caller.
         """
@@ -705,7 +704,18 @@ class UI(Structure):
         return Node.wrap(node_duplicate(ui_get_binary_uri(self.ui)))
 
 class Node(Structure):
-    """Data node (URI, string, integer, etc.)."""
+    """Data node (URI, string, integer, etc.).
+
+    A Node can be converted to the corresponding Python datatype, and all nodes
+    can be converted to strings, for example::
+
+       >>> world = lilv.World()
+       >>> i = world.new_int(42)
+       >>> print(i)
+       42
+       >>> int(i) * 2
+       84
+    """
     @classmethod
     def wrap(cls, node):
         return Node(node) if node else None
@@ -943,12 +953,12 @@ class Namespace():
     """Namespace prefix.
 
     Use attribute syntax to easily create URIs within this namespace, for
-    example:
-
-    .. code-block:: python
+    example::
 
-       ns = Namespace("http://example.org/")
-       foo = ns.foo # == http://example.org/foo
+       >>> world = lilv.World()
+       >>> ns = Namespace(world, "http://example.org/")
+       >>> print(ns.foo)
+       http://example.org/foo
     """
     def __init__(self, world, prefix):
         self.world  = world
@@ -964,7 +974,14 @@ class Namespace():
         return self.world.new_uri(self.prefix + suffix)
 
 class World(Structure):
-    """Library context."""
+    """Library context.
+
+    Includes a set of namespaces as the instance variable `ns`, so URIs can be constructed like::
+
+        uri = world.ns.lv2.Plugin
+
+    :ivar ns: Common LV2 namespace prefixes: atom, doap, foaf, lilv, lv2, midi, owl, rdf, rdfs, ui, xsd.
+    """
     def __init__(self):
         world = self
 
@@ -1021,7 +1038,7 @@ class World(Structure):
         `bundle_uri` must be a fully qualified URI to the bundle directory,
         with the trailing slash, eg. file:///usr/lib/lv2/foo.lv2/
 
-        Normal hosts should not need this function (use lilv_world_load_all()).
+        Normal hosts should not need this function (use load_all()).
 
         Hosts MUST NOT attach any long-term significance to bundle paths
         (e.g. in save files), since there are no guarantees they will remain
@@ -1034,7 +1051,7 @@ class World(Structure):
         """Load all specifications from currently loaded bundles.
 
         This is for hosts that explicitly load specific bundles, its use is not
-        necessary when using lilv_world_load_all().  This function parses the
+        necessary when using load_all().  This function parses the
         specifications and adds them to the model.
         """
         world_load_specifications(self.world)
@@ -1042,19 +1059,19 @@ class World(Structure):
     def load_plugin_classes(self):
         """Load all plugin classes from currently loaded specifications.
 
-        Must be called after lilv_world_load_specifications().  This is for hosts
+        Must be called after load_specifications().  This is for hosts
         that explicitly load specific bundles, its use is not necessary when using
-        lilv_world_load_all().
+        load_all().
         """
         world_load_plugin_classes(self.world)
 
     def unload_bundle(self, bundle_uri):
         """Unload a specific bundle.
 
-        This unloads statements loaded by lilv_world_load_bundle().  Note that this
+        This unloads statements loaded by load_bundle().  Note that this
         is not necessarily all information loaded from the bundle.  If any resources
-        have been separately loaded with liv_world_load_resource(), they must be
-        separately unloaded with lilv_world_unload_resource().
+        have been separately loaded with load_resource(), they must be
+        separately unloaded with unload_resource().
         """
         return world_unload_bundle(self.world, bundle_uri.node)
 
@@ -1075,7 +1092,7 @@ class World(Structure):
         The resource must be a subject (i.e. a URI or a blank node).
 
         This unloads all data loaded by a previous call to
-        lilv_world_load_resource() with the given `resource`.
+        load_resource() with the given `resource`.
         """
         return world_unload_resource(self.world, _as_uri(resource).node)
 
@@ -1204,8 +1221,8 @@ class Instance(Structure):
         """Activate a plugin instance.
 
            This resets all state information in the plugin, except for port data
-           locations (as set by lilv_instance_connect_port()).  This MUST be called
-           before calling lilv_instance_run().
+           locations (as set by connect_port()).  This MUST be called
+           before calling run().
         """
         if self.get_descriptor().activate:
             self.get_descriptor().activate(self.get_handle())