docs: Update accelerometer page with better range info. (#733)

Correct old notes about not being able to change the range.
Remove note already mentioned in the header, and move to header
note about needing to call an accelerometer function regulartly.

Indicate in the header the default range so that it can be removed
from each function description.

Use :param: and :return: in the function descriptions.

docs/accelerometer.rst

@@ -3,90 +3,86 @@ Accelerometer
 
 .. py:module:: microbit.accelerometer
 
-This object gives you access to the on-board accelerometer. The accelerometer
-also provides convenience functions for detecting gestures. The
-recognised gestures are: ``up``, ``down``, ``left``, ``right``, ``face up``,
-``face down``, ``freefall``, ``3g``, ``6g``, ``8g``, ``shake``.
+This object gives you access to the on-board accelerometer.
 
-By default MicroPython sets the accelerometer range to +/- 2g, changing the
-accelerometer range is currently not possible in MicroPython.
-The accelerometer returns a value in the range 0..1024 for each axis, which is
-then scaled accordingly.
+By default MicroPython sets the accelerometer range to +/- 2000 mg (``g`` being
+a unit of acceleration based on the standard gravity), which configures the
+maximum and minimum values returned by the acceleromter functions.
+The range can be changed via :func:`microbit.accelerometer.set_range`.
+
+The accelerometer also provides convenience functions for detecting gestures.
+The recognised gestures are represented as strings:
+``up``, ``down``, ``left``, ``right``, ``face up``, ``face down``,
+``freefall``, ``3g``, ``6g``, ``8g``, ``shake``.
+
+.. note::
+
+    Gestures are not updated in the background so there needs to be constant
+    calls to some accelerometer method to do the gesture detection.
+    Usually gestures can be detected using a loop with a small
+    :func:`microbit.sleep` delay.
 
 Functions
 =========
 
 .. py:function:: get_x()
 
-    Get the acceleration measurement in the ``x`` axis, as a positive or
-    negative integer, depending on the direction. The measurement is given in
-    milli-g. By default the accelerometer is configured with a range of +/- 2g,
-    and so this method will return within the range of +/- 2000mg.
+    :returns: The acceleration measurement in the ``x`` axis in milli-g,
+        as a positive or negative integer.
 
 .. py:function:: get_y()
 
-    Get the acceleration measurement in the ``y`` axis, as a positive or
-    negative integer, depending on the direction. The measurement is given in
-    milli-g. By default the accelerometer is configured with a range of +/- 2g,
-    and so this method will return within the range of +/- 2000mg.
+    :returns: The acceleration measurement in the ``y`` axis in milli-g,
+        as a positive or negative integer.
 
 .. py:function:: get_z()
 
-    Get the acceleration measurement in the ``z`` axis, as a positive or
-    negative integer, depending on the direction. The measurement is given in
-    milli-g. By default the accelerometer is configured with a range of +/- 2g,
-    and so this method will return within the range of +/- 2000mg.
+    :returns: The acceleration measurement in the ``z`` axis in milli-g,
+        as a positive or negative integer.
 
 .. py:function:: get_values()
 
-    Get the acceleration measurements in all axes at once, as a three-element
-    tuple of integers ordered as X, Y, Z.
-    By default the accelerometer is configured with a range of +/- 2g, and so
-    X, Y, and Z will be within the range of +/-2000mg.
+    :returns: The acceleration measurements in all axes at once, as a
+        three-element tuple of integers ordered as X, Y, Z.
 
 .. py:function:: get_strength()
 
     Get the acceleration measurement of all axes combined, as a positive
-    integer.  This is the Pythagorean sum of the X, Y and Z axes, with the
-    measurement given in milli-g.
-
-.. py:function:: current_gesture()
+    integer.  This is the Pythagorean sum of the X, Y and Z axes.
 
-    Return the name of the current gesture.
+    :returns: The combined acceleration strength of all the axes, in milli-g.
 
-.. note::
+.. py:function:: current_gesture()
 
-    MicroPython understands the following gesture names: ``"up"``, ``"down"``,
-    ``"left"``, ``"right"``, ``"face up"``, ``"face down"``, ``"freefall"``,
-    ``"3g"``, ``"6g"``, ``"8g"``, ``"shake"``. Gestures are always
-    represented as strings.
+    :returns: String with the name of the current gesture.
 
 .. py:function:: is_gesture(name)
 
-    Return True or False to indicate if the named gesture is currently active.
+    :param name: String with the name of the gesture to check.
+    :return: Boolean indicating if the named gesture is currently active.
 
 .. py:function:: was_gesture(name)
 
-    Return True or False to indicate if the named gesture was active since the
-    last call.
+    :param name: String with the name of the gesture to check.
+    :return: Boolean indicating if the named gesture was active since the
+        last call.
 
 .. py:function:: get_gestures()
 
-    Return a tuple of the gesture history. The most recent is listed last.
-    Also clears the gesture history before returning.
-
-.. note::
+    Get a historical list of the registered gestures.
 
-    Gestures are not updated in the background so there needs to be constant 
-    calls to some accelerometer method to do the gesture detection. Usually 
-    gestures can be detected using a loop with a small :func:`microbit.sleep` delay.
+    Calling this function clears the gesture history before returning.
+
+    :returns: A tuple of the gesture history, most recent is listed last.
 
 .. py:function:: set_range(value)
 
     Set the accelerometer sensitivity range, in g (standard gravity), to the
     closest values supported by the hardware, so it rounds to either ``1``,
     ``2``, ``4``, or ``8`` g.
 
+    :param value: New range for the accelerometer, an integer in ``g``.
+
 Examples
 --------