Updated documentation

docs/reference/ImagePalette.rst

@@ -9,10 +9,6 @@ represent the color palette of palette mapped images.
 
 .. note::
 
-    This module was never well-documented. It hasn't changed since 2001,
-    though, so it's probably safe for you to read the source code and puzzle
-    out the internals if you need to.
-
     The :py:class:`~PIL.ImagePalette.ImagePalette` class has several methods,
     but they are all marked as "experimental." Read that as you will. The
     ``[source]`` link is there for a reason.

src/PIL/ImagePalette.py

@@ -25,13 +25,13 @@ class ImagePalette:
     """
     Color palette for palette mapped images
 
-    :param mode: The mode to use for the Palette. See:
+    :param mode: The mode to use for the palette. See:
         :ref:`concept-modes`. Defaults to "RGB"
     :param palette: An optional palette. If given, it must be a bytearray,
         an array or a list of ints between 0-255 and of length ``size``
-        times the number of colors in ``mode``. The list must be aligned
-        by channel (All R values must be contiguous in the list before G
-        and B values.) Defaults to 0 through 255 per channel.
+        times the number of colors in ``mode``. The list must consist of
+        all channels for one color followed by the next color (e.g. RGBRGBRGB).
+        Defaults to an empty palette.
     :param size: An optional palette size. If given, it cannot be equal to
         or greater than 256. Defaults to 0.
     """