[libpng18] chore: Clean up the FILE * formulations in code and in documentation

We should use `FILE *` instead of `FILE*` or `(FILE*)`, consistently,
as we should for all other pointer types. Moreover, when we refer to
standard stdio file objects in comments and in documentation, we should
use the term "FILE objects" consistently.

Lastly, we clarify in a comment in example.c that `PNG_STDIO_SUPPORTED`
is true only when the stdio support is both available in the system and
accessible in the user's libpng build.

This is a cherry-pick of commit c63c5463903014c904b540216c2784023fb8c1c8
from branch 'libpng18'.

Reviewed-by: John Bowler <jbowler@acm.org>
Signed-off-by: Cosmin Truta <ctruta@gmail.com>

contrib/examples/pngpixel.c

@@ -184,11 +184,11 @@ int main(int argc, const char **argv)
                      compression_method, filter_method;
                   png_bytep row_tmp;
 
-                  /* Now associate the recently opened (FILE*) with the default
+                  /* Now associate the recently opened FILE object with the
-                   * libpng initialization functions.  Sometimes libpng is
+                   * default libpng initialization functions.  Sometimes libpng
-                   * compiled without stdio support (it can be difficult to do
+                   * is compiled without stdio support (it can be difficult to
-                   * in some environments); in that case you will have to write
+                   * do in some environments); in that case you will have to
-                   * your own read callback to read data from the (FILE*).
+                   * write your own read callback to read data from the stream.
                    */
                   png_init_io(png_ptr, f);
 

contrib/libtests/pngstest.c

@@ -595,7 +595,8 @@ newimage(Image *image)
    memset(image, 0, sizeof *image);
 }
 
-/* Reset the image to be read again - only needs to rewind the FILE* at present.
+/* Reset the image to be read again - only needs to rewind the FILE object at
+ * present.
  */
 static void
 resetimage(Image *image)

example.c

@@ -2,7 +2,7 @@
 
 /* example.c - an example of using libpng
  *
- * Maintained 2018-2024 Cosmin Truta
+ * Maintained 2018-2025 Cosmin Truta
  * Maintained 1998-2016 Glenn Randers-Pehrson
  * Maintained 1996-1997 Andreas Dilger
  * Written 1995-1996 Guy Eric Schalnat, Group 42, Inc.
@@ -179,11 +179,11 @@ int main(int argc, const char **argv)
  *    components.
  *
  * You do not have to read directly from a file.  You can read from memory or,
- * on systems that support it, from a <stdio.h> FILE*.  This is controlled by
+ * on systems that support <stdio.h>, from a FILE object.  This is controlled
- * the particular png_image_read_from_ function you call at the start.
+ * by the particular png_image_read_from_ function you call at the start.
- * Likewise, on write, you can write to a FILE* if your system supports it.
+ * Likewise, on write, you can write to a FILE object if your system supports
- * Check the macro PNG_STDIO_SUPPORTED to see if stdio support has been
+ * <stdio.h>.  The macro PNG_STDIO_SUPPORTED indicates if stdio is available
- * included in your libpng build.
+ * and accessible from your libpng build.
  *
  * If you read 16-bit (PNG_FORMAT_FLAG_LINEAR) data, you may need to write it
  * in the 8-bit format for display.  You do this by setting the convert_to_8bit

libpng-manual.txt

@@ -4164,7 +4164,7 @@ be written:
       int convert_to_8_bit, const void *buffer,
       png_int_32 row_stride, const void *colormap)
 
-      Write the image to the given (FILE*).
+      Write the image to the given FILE object.
 
 With all write APIs if image is in one of the linear formats with
 (png_uint_16) data then setting convert_to_8_bit will cause the output to be

libpng.3

@@ -4683,7 +4683,7 @@ be written:
       int convert_to_8_bit, const void *buffer,
       png_int_32 row_stride, const void *colormap)
 
-      Write the image to the given (FILE*).
+      Write the image to the given FILE object.
 
 With all write APIs if image is in one of the linear formats with
 (png_uint_16) data then setting convert_to_8_bit will cause the output to be

png.h

@@ -3163,7 +3163,7 @@ PNG_EXPORT(239, int, png_image_write_to_file, (png_imagep image,
 PNG_EXPORT(240, int, png_image_write_to_stdio, (png_imagep image, FILE *file,
    int convert_to_8_bit, const void *buffer, png_int_32 row_stride,
    const void *colormap));
-   /* Write the image to the given (FILE*). */
+   /* Write the image to the given FILE object. */
 #endif /* SIMPLIFIED_WRITE_STDIO */
 
 /* With all write APIs if image is in one of the linear formats with 16-bit

pngwrite.c

@@ -2333,7 +2333,7 @@ int PNGAPI
 png_image_write_to_stdio(png_imagep image, FILE *file, int convert_to_8bit,
     const void *buffer, png_int_32 row_stride, const void *colormap)
 {
-   /* Write the image to the given (FILE*). */
+   /* Write the image to the given FILE object. */
    if (image != NULL && image->version == PNG_IMAGE_VERSION)
    {
       if (file != NULL && buffer != NULL)