gh-85455: Add missing doc strings and improve docs (#21573)

* Add missing doc strings and improve docs

* Use imperative form

* Modify docstring wording

diff --git a/Doc/library/imghdr.rst b/Doc/library/imghdr.rst
index 318fe650776d2a3fdc72536d05693d6fa97484e7..630fd7019f94dea2cc22ad43439a0011466b2042 100644 (file)
--- a/Doc/library/imghdr.rst
+++ b/Doc/library/imghdr.rst
@@ -21,8 +21,8 @@ The :mod:`imghdr` module defines the following function:
 
 .. function:: what(file, h=None)
 
-   Tests the image data contained in the file named by *file*, and returns a
-   string describing the image type.  If optional *h* is provided, the *file*
+   Test the image data contained in the file named *file* and return a
+   string describing the image type.  If *h* is provided, the *file*
    argument is ignored and *h* is assumed to contain the byte stream to test.
 
    .. versionchanged:: 3.6

diff --git a/Lib/imghdr.py b/Lib/imghdr.py
index 6a372e66c7f2614a9444eeca3a5cdb06eb8e19a0..33868883470764fc2e00b08e9627a95a5cb5220f 100644 (file)
--- a/Lib/imghdr.py
+++ b/Lib/imghdr.py
@@ -14,6 +14,7 @@ warnings._deprecated(__name__, remove=(3, 13))
 #-------------------------#
 
 def what(file, h=None):
+    """Return the type of image contained in a file or byte stream."""
     f = None
     try:
         if h is None:
@@ -40,7 +41,7 @@ def what(file, h=None):
 tests = []
 
 def test_jpeg(h, f):
-    """JPEG data with JFIF or Exif markers; and raw JPEG"""
+    """Test for JPEG data with JFIF or Exif markers; and raw JPEG."""
     if h[6:10] in (b'JFIF', b'Exif'):
         return 'jpeg'
     elif h[:4] == b'\xff\xd8\xff\xdb':
@@ -49,34 +50,35 @@ def test_jpeg(h, f):
 tests.append(test_jpeg)
 
 def test_png(h, f):
+    """Verify if the image is a PNG."""
     if h.startswith(b'\211PNG\r\n\032\n'):
         return 'png'
 
 tests.append(test_png)
 
 def test_gif(h, f):
-    """GIF ('87 and '89 variants)"""
+    """Verify if the image is a GIF ('87 or '89 variants)."""
     if h[:6] in (b'GIF87a', b'GIF89a'):
         return 'gif'
 
 tests.append(test_gif)
 
 def test_tiff(h, f):
-    """TIFF (can be in Motorola or Intel byte order)"""
+    """Verify if the image is a TIFF (can be in Motorola or Intel byte order)."""
     if h[:2] in (b'MM', b'II'):
         return 'tiff'
 
 tests.append(test_tiff)
 
 def test_rgb(h, f):
-    """SGI image library"""
+    """test for the SGI image library."""
     if h.startswith(b'\001\332'):
         return 'rgb'
 
 tests.append(test_rgb)
 
 def test_pbm(h, f):
-    """PBM (portable bitmap)"""
+    """Verify if the image is a PBM (portable bitmap)."""
     if len(h) >= 3 and \
         h[0] == ord(b'P') and h[1] in b'14' and h[2] in b' \t\n\r':
         return 'pbm'
@@ -84,7 +86,7 @@ def test_pbm(h, f):
 tests.append(test_pbm)
 
 def test_pgm(h, f):
-    """PGM (portable graymap)"""
+    """Verify if the image is a PGM (portable graymap)."""
     if len(h) >= 3 and \
         h[0] == ord(b'P') and h[1] in b'25' and h[2] in b' \t\n\r':
         return 'pgm'
@@ -92,7 +94,7 @@ def test_pgm(h, f):
 tests.append(test_pgm)
 
 def test_ppm(h, f):
-    """PPM (portable pixmap)"""
+    """Verify if the image is a PPM (portable pixmap)."""
     if len(h) >= 3 and \
         h[0] == ord(b'P') and h[1] in b'36' and h[2] in b' \t\n\r':
         return 'ppm'
@@ -100,32 +102,35 @@ def test_ppm(h, f):
 tests.append(test_ppm)
 
 def test_rast(h, f):
-    """Sun raster file"""
+    """test for the Sun raster file."""
     if h.startswith(b'\x59\xA6\x6A\x95'):
         return 'rast'
 
 tests.append(test_rast)
 
 def test_xbm(h, f):
-    """X bitmap (X10 or X11)"""
+    """Verify if the image is a X bitmap (X10 or X11)."""
     if h.startswith(b'#define '):
         return 'xbm'
 
 tests.append(test_xbm)
 
 def test_bmp(h, f):
+    """Verify if the image is a BMP file."""
     if h.startswith(b'BM'):
         return 'bmp'
 
 tests.append(test_bmp)
 
 def test_webp(h, f):
+    """Verify if the image is a WebP."""
     if h.startswith(b'RIFF') and h[8:12] == b'WEBP':
         return 'webp'
 
 tests.append(test_webp)
 
 def test_exr(h, f):
+    """verify is the image ia a OpenEXR fileOpenEXR."""
     if h.startswith(b'\x76\x2f\x31\x01'):
         return 'exr'