doc: Corrected and improved size_hint doc

Author: inclement

kivy/uix/widget.py

@@ -961,8 +961,21 @@ def set_center_y(self, value):
     Only the :class:`~kivy.uix.layout.Layout` and
     :class:`~kivy.core.window.Window` classes make use of the hint.
 
-    The value is in percent as a float from 0. to 1., where 1. means the full
-    size of his parent. 0.5 represents 50%.
+    The size_hint is used by layouts for two purposes:
+
+    - When the layout considers widgets on their own rather than in
+      relation to its other children, the size_hint_x is a direct proportion
+      of the parent width, normally between 0.0 and 1.0. For instance, a
+      widget with ``size_hint_x=0.5`` in
+      a vertical BoxLayout will take up half the BoxLayout's width, or
+      a widget in a FloatLayout with ``size_hint_x=0.2`` will take up 20%
+      of the FloatLayout width. If the size_hint is greater than 1, the
+      widget will be wider than the parent.
+    - When multiple widgets can share a row of a layout, such as in a
+      horizontal BoxLayout, their widths will be their size_hint_x as a
+      fraction of the sum of widget size_hints. For instance, if the
+      size_hint_xs are (0.5, 1.0, 0.5), the first widget will have a
+      width of 25% of the parent width.
 
     :attr:`size_hint_x` is a :class:`~kivy.properties.NumericProperty` and
     defaults to 1.
@@ -974,7 +987,8 @@ def set_center_y(self, value):
     :attr:`size_hint_y` is a :class:`~kivy.properties.NumericProperty` and
     defaults to 1.
 
-    See :attr:`size_hint_x` for more information.
+    See :attr:`size_hint_x` for more information, but with widths and heights
+    swapped.
     '''
 
     size_hint = ReferenceListProperty(size_hint_x, size_hint_y)