Some documentation cleanup and improvements

docs/changelog.md

@@ -2,6 +2,12 @@
 
 Note: releases are listed from latest to oldest.
 
+## Version 1.0 (in development)
+
+- Ensured that the `PLUM_FILENAME`, `PLUM_BUFFER` and `PLUM_CALLBACK` constants are always `size_t` as documented
+- Enforced the size limitation on the value returned by a callback when using the `PLUM_CALLBACK` loading/storing mode
+- Some minor documentation updates
+
 ## Version 0.3 (10 January 2022)
 
 - New functions: `plum_load_image_limited`, `plum_check_limited_image_size`, `plum_append_metadata`

docs/colors.md

@@ -9,17 +9,17 @@
 Regardless of the actual formats used for color and pixel data in image files, the library uses a number of standard
 color formats and converts to and from those formats respectively when loading and generating image files.
 The user chooses which color format to use via an argument when loading an image (or a struct member when creating one
-manually); therefore, while the library supports processing data in all supported color formats, users only need to
-choose one and use the one they prefer.
+manually); therefore, while the library can process data in all supported color formats, users only need to choose one
+and use the one they prefer.
 
 All color formats contain red, green, blue and alpha channels.
-There is no dedicated support for grayscale or no transparency formats; images using those formats will be converted
+There is no dedicated support for grayscale or no-transparency formats; images using those formats will be converted
 to RGBA when loaded.
 
 All color formats use fixed-width integers for color values.
 The channels are always in RGBA order from least significant to most significant bit; in other words, the red channel
 always takes up the least significant bits and the alpha channel always takes up the most significant bits.
-There are no unused bits, and the three color channels always have the same bit width.
+There are no unused bits, and the three color channels (red, green and blue) always have the same bit width.
 
 There are [helper macros][macros] available to generate color values out of their components and extract those
 components from a color value.
@@ -83,7 +83,7 @@ The palette itself stores colors in whichever color format is set for the image
 member).
 
 An image uses indexed-color mode if its `palette` member (and therefore, the corresponding `palette16`, `palette32`
-and `palette64` members, which alias `palette`) is not null.
+and `palette64` members, which alias `palette`) is not `NULL`.
 In this case, the `max_palette_index` member determines the maximum valid index value (and thus implicitly the size of
 the palette); note that this maximum is _inclusive_, so that a `max_palette_index` of 3 indicates a palette with four
 colors (with indexes ranging between 0 and 3).

docs/constants.md

@@ -123,7 +123,7 @@ Naturally, when flags are combined with a bitwise OR (`|`), the "zero" member (w
 default and can be left out.
 Groups also have a mask member, which can be used to mask out that group's bits (for checking, etc.)
 
-Note that, since members of this struct are meant to be combined via bitwise OR (`|`), their values are **not**
+Note that, since members of this enumeration are meant to be combined via bitwise OR (`|`), their values are **not**
 consecutive.
 
 **Color format flags:** these flags are used to determine the image's or the color buffer's color format.

docs/conventions.md

@@ -8,7 +8,7 @@
 The library follows a number of conventions to make it easier to use.
 
 All public identifiers (functions, macros, etc.) begin with `plum_` or `PLUM_`.
-Macros and constants are all uppercase; functions and `struct` tags are all lowercase.
+Macros and constants are all uppercase; functions and `struct` and `enum` tags are all lowercase.
 In all cases, words are separated by underscores and capitalization is not mixed.
 There is a number of macros that [don't follow the prefix rules][unprefixed], but those macros aren't included by
 default, and the user has to explicitly enable them with a `#define` in order to use them.
@@ -28,6 +28,7 @@ type, use `32` for both 32-bit formats, since they both use `uint32_t` values.
 All functions that take `restrict` pointer arguments use the `restrict` keyword in the documentation.
 If the library header is included in a C89 source file, as determined by testing the `__STDC_VERSION__` standard
 definition, the `restrict` keyword will be taken out through a macro, since that keyword doesn't exist in C89.
+Likewise, if the library header is included in a C++ source file, the `restrict` keyword will also be removed.
 However, since the library does expect `restrict` semantics, the keyword is still included in the documentation.
 
 ## Limitations
@@ -52,11 +53,13 @@ here for completeness.
 - The stack is large enough to hold the library's temporary arrays.
   The compiler should be able to determine the maximum stack usage of the library, as it doesn't use any dynamic stack
   allocation (like VLAs or `alloca`) and there are no recursive functions that allocate large automatic arrays.
-  While it isn't particularly large for a common desktop machine, systems with very small stacks (like 32 KB) might
-  run into stack overflows.
+  While the requirement isn't particularly large for a common desktop machine, systems with very small stacks (like 32
+  KB) might run into stack overflows.
 
 In particular, the library doesn't make any assumptions about endianness, floating point format, system locale or
 character encoding.
+(However, some calculations are optimized for IEEE double-precision floating point and will be more accurate when that
+format is used.)
 
 * * *
 

docs/formats.md

@@ -97,7 +97,7 @@ The library will ignore the image's version number (i.e., it will parse `GIF87a`
 will always generate `GIF89a` files.
 
 The GIF format doesn't support the [`PLUM_DISPOSAL_REPLACE`][disposals] disposal method, or any of the combinations
-including it; that will be converted when generating an image file.
+including it; they will be converted to their non-replacing counterparts when generating an image file.
 
 Valid [frame durations][durations] are between 0 and 655.35 seconds, in intervals of 0.01 seconds; values will be
 rounded accordingly when generating a file.
@@ -194,7 +194,7 @@ data.
 
 Although the library supports loading all sorts of uncommon JPEG files, it will always generate baseline JPEG/JFIF
 files (8-bit precision, Huffman coding, YCbCr color space, 4:2:0 chroma subsampling).
-This aims to increase the compatibility of said files, since many decoders don't support uncommmon JPEG formats.
+This aims to increase the compatibility of said files, since many decoders don't support uncommon JPEG formats.
 
 The JPEG specification doesn't define the color formats an image can use.
 Instead, it expects applications to agree on the meaning of component IDs.

docs/functions.md

@@ -910,8 +910,8 @@ This function returns the highest palette index in use for an image.
 If the function succeeds, it returns the highest palette index used by any pixel in the image.
 (This will be a value between 0 and 255.)
 
-If the function fails, it returns a negated [error constant][errors] (for example, if a `PLUM_ERR_NO_DATA` error
-occurs, the function will return `-PLUM_ERR_NO_DATA`).
+If the function fails, it returns a negated [error constant][errors]. For example, if it fails due to a
+`PLUM_ERR_NO_DATA` error, it will return `-PLUM_ERR_NO_DATA`.
 Since all error constants are positive, the function will always return a negative value on error.
 
 **Error values:**

docs/macros.md

@@ -197,9 +197,10 @@ The following macros can be defined by the user (before including the library he
   If this macro is defined, the user **must** provide their own `typedef` definitions for the `uint8_t`, `uint16_t`,
   `uint32_t` and `uint64_t` types _before_ including the library header; otherwise, compilation will fail.
 - `PLUM_NO_VLA`: disables the use of [VLA-based macros](#pixel-array-macros) and sets `PLUM_VLA_SUPPORT` to zero.
-  This can be used to avoid compilation errors if the compiler doesn't support VLAs, but it also doesn't use the
-  standard macros that indicate that.
-- `PLUM_NO_ANON_MEMBERS`: disables anonymous unions in the [`plum_image`] struct and sets `PLUM_ANON_MEMBERS` to zero.
+  This can be used to avoid compilation errors if the compiler doesn't support VLAs, but also doesn't use the standard
+  macros that indicate that.
+- `PLUM_NO_ANON_MEMBERS`: disables anonymous unions in the [`plum_image`][image] struct and sets `PLUM_ANON_MEMBERS`
+  to zero.
   This can be used if the compiler doesn't support this feature, even in C11+ or C++ mode.
 
 Note that the library will internally use some additional feature-test macros to function properly; all of these
@@ -228,7 +229,7 @@ All of these macros are equivalent to one of the macros defined above.
 - `PIXEL8`, `PIXEL16`, `PIXEL32`, `PIXEL64`: equivalent to [`PLUM_PIXEL_8`](#pixel-index-macros) and the like.
 - `PIXARRAY`: equivalent to [`PLUM_PIXEL_ARRAY`](#array-declaration).
   Available only when [`PLUM_VLA_SUPPORT`](#feature-test-macros) is non-zero.
-- `PIXARRAY_T`: equivañent to [`PLUM_PIXEL_ARRAY_TYPE`](#array-type).
+- `PIXARRAY_T`: equivalent to [`PLUM_PIXEL_ARRAY_TYPE`](#array-type).
   Available only when [`PLUM_VLA_SUPPORT`](#feature-test-macros) is non-zero.
 - `PIXELS8`, `PIXELS16`, `PIXELS32`, `PIXELS64`: equivalent to [`PLUM_PIXELS_8`](#array-casts) and the like.
   Available only when [`PLUM_VLA_SUPPORT`](#feature-test-macros) is non-zero.

docs/structs.md

@@ -1,6 +1,7 @@
 # Data structures
 
-The main data structure used by the library is the `plum_image` data structure, which represents an image.
+The main data structure used by the library is the [`plum_image`](#plum_image) data structure, which represents an
+image.
 All image data is contained by this structure, as well as some minimal associated metadata and linked memory
 allocations.
 Other structures are used to hold some ancillary data and/or to pass data to functions, and they are also described
@@ -47,7 +48,7 @@ struct plum_image {
 };
 ```
 
-(Note: in C89 mode, the `palette` and `data` members replace their respective anonymous unions, and the convenience
+(Note: in C89 mode, the `palette` and `data` members replace their respective anonymous unions, and the corresponding
 typed aliases are not available.)
 
 This structure contains an image. An image is fully defined by its size and its pixel data, in the format determined

docs/version.md

@@ -15,7 +15,7 @@ minor.
 The **major** version changes whenever there is a breaking change in the library.
 Major version 0 (i.e., version 0.x) is used to indicate that the library isn't stable yet, and interfaces may change
 between releases.
-Major version 1 will be the first stable release, and further major versions will indicate breaking changes in the
+Major version 1 is the first stable release, and further major versions will indicate breaking changes in the
 library's interface or functionality.
 
 The **minor** version changes with every release that isn't a major release; major releases reset it back to zero.