doc: tweaks and standardized layout to uix/behaviors/knspace.py

Author: Zen-CODE

kivy/uix/behaviors/knspace.py

@@ -8,8 +8,9 @@
     This code is still experimental, and its API is subject to change in a
     future version.
 
-Provides namespace functionality for Kivy objects. It allows kivy objects
-to be named and then accessed using the namespace.
+The :class:`KNSpaceBehavior` `mixin <https://en.wikipedia.org/wiki/Mixin>`_
+class provides namespace functionality for Kivy objects. It allows kivy objects
+to be named and then accessed using namespaces.
 
 :class:`KNSpace` instances are the namespaces that store the named objects
 in Kivy :class:`~kivy.properties.ObjectProperty` instances.
@@ -18,11 +19,10 @@
 namespace and will point to a :attr:`~kivy.uix.widget.proxy_ref` of the
 derived object.
 
-
 Basic examples
 --------------
 
-By default, there's only a single namespace; the :attr:`knspace` namespace. The
+By default, there's only a single namespace: the :attr:`knspace` namespace. The
 simplest example is adding a widget to the namespace:
 
 .. code-block:: python
@@ -31,8 +31,8 @@
     widget = Widget()
     knspace.my_widget = widget
 
-This adds an kivy :class:`~kivy.properties.ObjectProperty` with `rebind=True`
-and `allownone=True` to the :attr:`knspace` namespace with property name
+This adds a kivy :class:`~kivy.properties.ObjectProperty` with `rebind=True`
+and `allownone=True` to the :attr:`knspace` namespace with a property name
 `my_widget`. And the property now also points to this widget.
 
 This can be done automatically with:
@@ -68,7 +68,7 @@ class MyWidget(KNSpaceBehavior, Widget):
 Setting the namespace
 ---------------------
 
-One can also create their own namespace rather than using the default
+One can also create ones own namespace rather than using the default
 :attr:`knspace` by directly setting :attr:`KNSpaceBehavior.knspace`:
 
 .. code-block:: python
@@ -83,7 +83,7 @@ class MyWidget(KNSpaceBehavior, Widget):
 Initially, `my_widget` is added to the default namespace, but when the widget's
 namespace is changed to `my_new_namespace`, the reference to `my_widget` is
 moved to that namespace. We could have also of course first set the namespace
-to `my_new_namespace` and then named the widget as `my_widget`, thereby
+to `my_new_namespace` and then have named the widget `my_widget`, thereby
 avoiding the initial assignment to the default namespace.
 
 Similarly, in kv:
@@ -100,7 +100,7 @@ class MyWidget(KNSpaceBehavior, Widget):
 ------------------------
 
 In the previous example, we directly set the namespace we wished to use.
-In the following example we inherit it from our parent, so we only have to set
+In the following example, we inherit it from the parent, so we only have to set
 it once:
 
 .. code-block:: kv
@@ -128,7 +128,7 @@ class MyWidget(KNSpaceBehavior, Widget):
 use. If none are found, it uses the default :attr:`knspace`.
 
 When `MyComplexWidget` is created, it still used the default namespace.
-However, when we assigned to the root widget its new_namespace, all its
+However, when we assigned the root widget its new namespace, all its
 children switched to using that new namespace as well. So `new_knspace` now
 contains `label1` and `label2` as well as `my_complex`.
 
@@ -196,7 +196,7 @@ class MyWidget(KNSpaceBehavior, Widget):
 
 Further, because both the namespace :class:`~kivy.properties.ObjectProperty`
 references, and :atrr:`KNSpaceBehavior.knspace` have `rebind=True`, the
-text of the `MyComplexWidget` label is rebind to match the text of
+text of the `MyComplexWidget` label is rebound to match the text of
 `MyPrettyWidget` when either the root's namespace changes or when the
 `root.knspace.pretty` property changes, as expected.
 
@@ -379,11 +379,12 @@ def fork(self):
 
 
 class KNSpaceBehavior(object):
-    '''Inheriting from this class allows naming of the inherited object, which
-    is then added to the associated namespace :attr:`knspace` and accessible
+    '''Inheriting from this class allows naming of the inherited objects, which
+    are then added to the associated namespace :attr:`knspace` and accessible
     through it.
 
-    See :mod:`~kivy.uix.behaviors.knspace` for details.
+    Please see the :mod:`knspace behaviors module <kivy.uix.behaviors.knspace>`
+    documentation for more information.
     '''
 
     _knspace = ObjectProperty(None, allownone=True)