Tidy up some prototypes

docs/api_encoders.rst

@@ -12,6 +12,12 @@ frames for output to disk. However, picamera also has classes representing
 these classes directly, but advanced users may find them useful as base classes
 for :ref:`custom_encoders`.
 
+.. note::
+
+    It is strongly recommended that you familiarize yourself with the
+    :mod:`~picamera.mmalobj` layer before attempting to understand the encoder
+    classes as they deal with several concepts native to that layer.
+
 The inheritance diagram for the following classes is displayed below:
 
 .. image:: images/encoder_classes.*

picamera/encoders.py

@@ -277,6 +277,8 @@ def _callback(self, port, buf):
 
     def _callback_write(self, buf, key=PiVideoFrameType.frame):
         """
+        _callback_write(buf, key=PiVideoFrameType.frame)
+
         Writes output on behalf of the encoder callback function.
 
         This method is called by :meth:`_callback` to handle writing to an
@@ -312,6 +314,8 @@ def _callback_write(self, buf, key=PiVideoFrameType.frame):
 
     def _open_output(self, output, key=PiVideoFrameType.frame):
         """
+        _open_output(output, key=PiVideoFrameType.frame)
+
         Opens *output* and associates it with *key* in :attr:`outputs`.
 
         If *output* is a string, this method opens it as a filename and keeps
@@ -331,6 +335,8 @@ def _open_output(self, output, key=PiVideoFrameType.frame):
 
     def _close_output(self, key=PiVideoFrameType.frame):
         """
+        _close_output(key=PiVideoFrameType.frame)
+
         Closes the output associated with *key* in :attr:`outputs`.
 
         Closes the output object associated with the specified *key*, and
@@ -564,6 +570,8 @@ def _create_encoder(self, format):
 
     def _callback_write(self, buf, key=PiVideoFrameType.frame):
         """
+        _callback_write(buf, key=PiVideoFrameType.frame)
+
         Overridden to strip alpha bytes when required.
         """
         if self._strip_alpha:

picamera/streams.py

@@ -722,6 +722,8 @@ def copy_to(
             self, output, size=None, seconds=None,
             first_frame=PiVideoFrameType.sps_header):
         """
+        copy_to(output, size=None, seconds=None, first_frame=PiVideoFrameType.sps_header)
+
         Copies content from the stream to *output*.
 
         By default, this method copies all complete frames from the circular