DOC: add documentation for common parameters

Author: mgeier

doc/api.rst

@@ -11,6 +11,29 @@ API Documentation
    MixerAndRecorder
    RingBuffer
 
+Common parameters that are shared by most commands:
+
+``start``
+   Desired time at which the playback/recording should be started.
+   The actual time will be stored in the ``actual_time`` field of the
+   returned action.
+
+``time``
+   Desired time at which the command should be executed.
+   The actual time will be stored in the ``actual_time`` field of the
+   returned action.
+
+``allow_belated``
+   Use ``False`` to cancel the command in case the requested time cannot be met.
+   The ``actual_time`` field will be set to ``0.0`` in this case.
+   Use ``True`` to execute the command nevertheless.
+   Even if the requested time was met, the ``actual_time`` might be slightly
+   different due to rounding.
+
+All commands return a corresponding "action", which can be compared against the
+active `actions`, and can be used  as input for `cancel()` and `wait()`.
+
+
 .. autoclass:: Mixer
    :members: play_buffer, play_ringbuffer, actions, cancel, wait, stats,
              fetch_and_reset_stats

src/rtmixer.py

@@ -162,7 +162,7 @@ def __init__(self, **kwargs):
     def play_buffer(self, buffer, channels, start=0, allow_belated=True):
         """Send a buffer to the callback to be played back.
 
-        After that, the *buffer* must not be written to anymore.
+        After calling this, the *buffer* must not be written to anymore.
 
         """
         channels, mapping = self._check_channels(channels, 'output')