Merging upstream version 125.0.1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

10 files changed, 521 insertions, 465 deletions

diff --git a/third_party/jpeg-xl/lib/include/jxl/cms_interface.h b/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
index c164eaccb5..25c700867a 100644
--- a/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
+++ b/third_party/jpeg-xl/lib/include/jxl/cms_interface.h
@@ -29,10 +29,10 @@ extern "C" {
 
 /** Parses an ICC profile and populates @p c and @p cmyk with the data.
  *
- * @param user_data JxlCmsInterface::set_fields_data passed as-is.
+ * @param user_data @ref JxlCmsInterface::set_fields_data passed as-is.
  * @param icc_data the ICC data to parse.
  * @param icc_size how many bytes of icc_data are valid.
- * @param c a JxlColorEncoding to populate if applicable.
+ * @param c a @ref JxlColorEncoding to populate if applicable.
  * @param cmyk a boolean to set to whether the colorspace is a CMYK colorspace.
  * @return Whether the relevant fields in @p c were successfully populated.
  */
@@ -66,22 +66,23 @@ typedef struct {
 
 /** Allocates and returns the data needed for @p num_threads parallel transforms
  * from the @p input colorspace to @p output, with up to @p pixels_per_thread
- * pixels to transform per call to JxlCmsInterface::run. @p init_data comes
- * directly from the JxlCmsInterface instance. Since @c run only receives the
- * data returned by @c init, a reference to @p init_data should be kept there
- * if access to it is desired in @c run. Likewise for JxlCmsInterface::destroy.
+ * pixels to transform per call to @ref JxlCmsInterface::run. @p init_data comes
+ * directly from the @ref JxlCmsInterface instance. Since @c run only receives
+ * the data returned by @c init, a reference to @p init_data should be kept
+ * there if access to it is desired in @c run. Likewise for @ref
+ * JxlCmsInterface::destroy.
  *
  * The ICC data in @p input and @p output is guaranteed to outlive the @c init /
  * @c run / @c destroy cycle.
  *
- * @param init_data JxlCmsInterface::init_data passed as-is.
+ * @param init_data @ref JxlCmsInterface::init_data passed as-is.
  * @param num_threads the maximum number of threads from which
- *        JxlCmsInterface::run will be called.
+ *        @ref JxlCmsInterface::run will be called.
  * @param pixels_per_thread the maximum number of pixels that each call to
- *        JxlCmsInterface::run will have to transform.
+ *        @ref JxlCmsInterface::run will have to transform.
  * @param input_profile the input colorspace for the transform.
- * @param output_profile the colorspace to which JxlCmsInterface::run should
- *        convert the input data.
+ * @param output_profile the colorspace to which @ref JxlCmsInterface::run
+ * should convert the input data.
  * @param intensity_target for colorspaces where luminance is relative
  *        (essentially: not PQ), indicates the luminance at which (1, 1, 1) will
  *        be displayed. This is useful for conversions between PQ and a relative
@@ -135,7 +136,7 @@ typedef float* (*jpegxl_cms_get_buffer_func)(void* user_data, size_t thread);
  * @param output_buffer the buffer receiving the transformed pixel data.
  * @param num_pixels the number of pixels to transform from @p input to
  * @p output.
- * @return JXL_TRUE on success, JXL_FALSE on failure.
+ * @return ::JXL_TRUE on success, ::JXL_FALSE on failure.
  */
 typedef JXL_BOOL (*jpegxl_cms_run_func)(void* user_data, size_t thread,
                                         const float* input_buffer,
@@ -226,7 +227,7 @@ typedef void (*jpegxl_cms_destroy_func)(void*);
 typedef struct {
   /** CMS-specific data that will be passed to @ref set_fields_from_icc. */
   void* set_fields_data;
-  /** Populates a JxlColorEncoding from an ICC profile. */
+  /** Populates a @ref JxlColorEncoding from an ICC profile. */
   jpegxl_cms_set_fields_from_icc_func set_fields_from_icc;
 
   /** CMS-specific data that will be passed to @ref init. */
diff --git a/third_party/jpeg-xl/lib/include/jxl/codestream_header.h b/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
index fb71484233..e60eb03355 100644
--- a/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
+++ b/third_party/jpeg-xl/lib/include/jxl/codestream_header.h
@@ -71,7 +71,7 @@ typedef struct {
 } JxlPreviewHeader;
 
 /** The codestream animation header, optionally present in the beginning of
- * the codestream, and if it is it applies to all animation frames, unlike
+ * the codestream, and if it is it applies to all animation frames, unlike @ref
  * JxlFrameHeader which applies to an individual frame.
  */
 typedef struct {
@@ -166,12 +166,12 @@ typedef struct {
    * it to to the original color profile. The decoder also does not convert to
    * the target display color profile. To convert the pixel data produced by
    * the decoder to the original color profile, one of the JxlDecoderGetColor*
-   * functions needs to be called with @ref JXL_COLOR_PROFILE_TARGET_DATA to get
-   * the color profile of the decoder output, and then an external CMS can be
-   * used for conversion.
-   * Note that for lossy compression, this should be set to false for most use
-   * cases, and if needed, the image should be converted to the original color
-   * profile after decoding, as described above.
+   * functions needs to be called with
+   * ::JXL_COLOR_PROFILE_TARGET_DATA to get the color profile of the decoder
+   * output, and then an external CMS can be used for conversion. Note that for
+   * lossy compression, this should be set to false for most use cases, and if
+   * needed, the image should be converted to the original color profile after
+   * decoding, as described above.
    */
   JXL_BOOL uses_original_profile;
 
@@ -194,17 +194,19 @@ typedef struct {
    * grayscale data, or 3 for colored data. This count does not include
    * the alpha channel or other extra channels. To check presence of an alpha
    * channel, such as in the case of RGBA color, check alpha_bits != 0.
-   * If and only if this is 1, the JxlColorSpace in the JxlColorEncoding is
-   * JXL_COLOR_SPACE_GRAY.
+   * If and only if this is 1, the @ref JxlColorSpace in the @ref
+   * JxlColorEncoding is
+   * ::JXL_COLOR_SPACE_GRAY.
    */
   uint32_t num_color_channels;
 
   /** Number of additional image channels. This includes the main alpha channel,
    * but can also include additional channels such as depth, additional alpha
    * channels, spot colors, and so on. Information about the extra channels
-   * can be queried with JxlDecoderGetExtraChannelInfo. The main alpha channel,
-   * if it exists, also has its information available in the alpha_bits,
-   * alpha_exponent_bits and alpha_premultiplied fields in this JxlBasicInfo.
+   * can be queried with @ref JxlDecoderGetExtraChannelInfo. The main alpha
+   * channel, if it exists, also has its information available in the
+   * alpha_bits, alpha_exponent_bits and alpha_premultiplied fields in this @ref
+   * JxlBasicInfo.
    */
   uint32_t num_extra_channels;
 
@@ -388,7 +390,8 @@ typedef struct {
 /** The header of one displayed frame or non-coalesced layer. */
 typedef struct {
   /** How long to wait after rendering in ticks. The duration in seconds of a
-   * tick is given by tps_numerator and tps_denominator in JxlAnimationHeader.
+   * tick is given by tps_numerator and tps_denominator in @ref
+   * JxlAnimationHeader.
    */
   uint32_t duration;
 
@@ -396,9 +399,9 @@ typedef struct {
    * interpreted from most-significant to least-significant as hour, minute,
    * second, and frame. If timecode is nonzero, it is strictly larger than that
    * of a previous frame with nonzero duration. These values are only available
-   * if have_timecodes in JxlAnimationHeader is JXL_TRUE.
-   * This value is only used if have_timecodes in JxlAnimationHeader is
-   * JXL_TRUE.
+   * if have_timecodes in @ref JxlAnimationHeader is ::JXL_TRUE.
+   * This value is only used if have_timecodes in @ref JxlAnimationHeader is
+   * ::JXL_TRUE.
    */
   uint32_t timecode;
 
diff --git a/third_party/jpeg-xl/lib/include/jxl/color_encoding.h b/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
index 928117e8dd..e6325dcb30 100644
--- a/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
+++ b/third_party/jpeg-xl/lib/include/jxl/color_encoding.h
@@ -24,9 +24,9 @@ extern "C" {
 typedef enum {
   /** Tristimulus RGB */
   JXL_COLOR_SPACE_RGB,
-  /** Luminance based, the primaries in JxlColorEncoding must be ignored. This
-   * value implies that num_color_channels in JxlBasicInfo is 1, any other value
-   * implies num_color_channels is 3. */
+  /** Luminance based, the primaries in @ref JxlColorEncoding must be ignored.
+   * This value implies that num_color_channels in @ref JxlBasicInfo is 1, any
+   * other value implies num_color_channels is 3. */
   JXL_COLOR_SPACE_GRAY,
   /** XYB (opsin) color space */
   JXL_COLOR_SPACE_XYB,
@@ -35,18 +35,18 @@ typedef enum {
 } JxlColorSpace;
 
 /** Built-in whitepoints for color encoding. When decoding, the numerical xy
- * whitepoint value can be read from the JxlColorEncoding white_point field
+ * whitepoint value can be read from the @ref JxlColorEncoding white_point field
  * regardless of the enum value. When encoding, enum values except
- * JXL_WHITE_POINT_CUSTOM override the numerical fields. Some enum values match
- * a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however the
- * white point and RGB primaries are separate enums here.
+ * ::JXL_WHITE_POINT_CUSTOM override the numerical fields. Some enum values
+ * match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC 23091-2:2019(E)), however
+ * the white point and RGB primaries are separate enums here.
  */
 typedef enum {
   /** CIE Standard Illuminant D65: 0.3127, 0.3290 */
   JXL_WHITE_POINT_D65 = 1,
-  /** White point must be read from the JxlColorEncoding white_point field, or
-   * as ICC profile. This enum value is not an exact match of the corresponding
-   * CICP value. */
+  /** White point must be read from the @ref JxlColorEncoding white_point field,
+   * or as ICC profile. This enum value is not an exact match of the
+   * corresponding CICP value. */
   JXL_WHITE_POINT_CUSTOM = 2,
   /** CIE Standard Illuminant E (equal-energy): 1/3, 1/3 */
   JXL_WHITE_POINT_E = 10,
@@ -55,10 +55,10 @@ typedef enum {
 } JxlWhitePoint;
 
 /** Built-in primaries for color encoding. When decoding, the primaries can be
- * read from the JxlColorEncoding primaries_red_xy, primaries_green_xy and
+ * read from the @ref JxlColorEncoding primaries_red_xy, primaries_green_xy and
  * primaries_blue_xy fields regardless of the enum value. When encoding, the
- * enum values except JXL_PRIMARIES_CUSTOM override the numerical fields. Some
- * enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC
+ * enum values except ::JXL_PRIMARIES_CUSTOM override the numerical fields.
+ * Some enum values match a subset of CICP (Rec. ITU-T H.273 | ISO/IEC
  * 23091-2:2019(E)), however the white point and RGB primaries are separate
  * enums here.
  */
@@ -66,7 +66,7 @@ typedef enum {
   /** The CIE xy values of the red, green and blue primaries are: 0.639998686,
      0.330010138; 0.300003784, 0.600003357; 0.150002046, 0.059997204 */
   JXL_PRIMARIES_SRGB = 1,
-  /** Primaries must be read from the JxlColorEncoding primaries_red_xy,
+  /** Primaries must be read from the @ref JxlColorEncoding primaries_red_xy,
    * primaries_green_xy and primaries_blue_xy fields, or as ICC profile. This
    * enum value is not an exact match of the corresponding CICP value. */
   JXL_PRIMARIES_CUSTOM = 2,
@@ -94,7 +94,7 @@ typedef enum {
   JXL_TRANSFER_FUNCTION_DCI = 17,
   /** As specified in Rec. ITU-R BT.2100-1 (HLG) */
   JXL_TRANSFER_FUNCTION_HLG = 18,
-  /** Transfer function follows power law given by the gamma value in
+  /** Transfer function follows power law given by the gamma value in @ref
      JxlColorEncoding. Not a CICP value. */
   JXL_TRANSFER_FUNCTION_GAMMA = 65535,
 } JxlTransferFunction;
@@ -118,7 +118,7 @@ typedef struct {
    */
   JxlColorSpace color_space;
 
-  /** Built-in white point. If this value is JXL_WHITE_POINT_CUSTOM, must
+  /** Built-in white point. If this value is ::JXL_WHITE_POINT_CUSTOM, must
    * use the numerical whitepoint values from white_point_xy.
    */
   JxlWhitePoint white_point;
@@ -126,10 +126,10 @@ typedef struct {
   /** Numerical whitepoint values in CIE xy space. */
   double white_point_xy[2];
 
-  /** Built-in RGB primaries. If this value is JXL_PRIMARIES_CUSTOM, must
+  /** Built-in RGB primaries. If this value is ::JXL_PRIMARIES_CUSTOM, must
    * use the numerical primaries values below. This field and the custom values
    * below are unused and must be ignored if the color space is
-   * JXL_COLOR_SPACE_GRAY or JXL_COLOR_SPACE_XYB.
+   * ::JXL_COLOR_SPACE_GRAY or ::JXL_COLOR_SPACE_XYB.
    */
   JxlPrimaries primaries;
 
@@ -145,7 +145,8 @@ typedef struct {
   /** Transfer function if have_gamma is 0 */
   JxlTransferFunction transfer_function;
 
-  /** Gamma value used when transfer_function is JXL_TRANSFER_FUNCTION_GAMMA
+  /** Gamma value used when transfer_function is @ref
+   * JXL_TRANSFER_FUNCTION_GAMMA
    */
   double gamma;
 
diff --git a/third_party/jpeg-xl/lib/include/jxl/decode.h b/third_party/jpeg-xl/lib/include/jxl/decode.h
index eaee70fa61..599b8336f3 100644
--- a/third_party/jpeg-xl/lib/include/jxl/decode.h
+++ b/third_party/jpeg-xl/lib/include/jxl/decode.h
@@ -66,12 +66,12 @@ typedef enum {
  * @p size doesn't need to be a full image, only the beginning of the file.
  *
  * @return a flag indicating if a JPEG XL signature was found and what type.
- *  - @ref JXL_SIG_NOT_ENOUGH_BYTES if not enough bytes were passed to
+ *  - ::JXL_SIG_NOT_ENOUGH_BYTES if not enough bytes were passed to
  *    determine if a valid signature is there.
- *  - @ref JXL_SIG_INVALID if no valid signature found for JPEG XL decoding.
- *  - @ref JXL_SIG_CODESTREAM if a valid JPEG XL codestream signature was
+ *  - ::JXL_SIG_INVALID if no valid signature found for JPEG XL decoding.
+ *  - ::JXL_SIG_CODESTREAM if a valid JPEG XL codestream signature was
  *    found.
- *  - @ref JXL_SIG_CONTAINER if a valid JPEG XL container signature was found.
+ *  - ::JXL_SIG_CONTAINER if a valid JPEG XL container signature was found.
  */
 JXL_EXPORT JxlSignature JxlSignatureCheck(const uint8_t* buf, size_t len);
 
@@ -115,7 +115,7 @@ JXL_EXPORT void JxlDecoderDestroy(JxlDecoder* dec);
 
 /**
  * Return value for @ref JxlDecoderProcessInput.
- * The values from @ref JXL_DEC_BASIC_INFO onwards are optional informative
+ * The values from ::JXL_DEC_BASIC_INFO onwards are optional informative
  * events that can be subscribed to, they are never returned if they
  * have not been registered with @ref JxlDecoderSubscribeEvents.
  */
@@ -123,12 +123,12 @@ typedef enum {
   /** Function call finished successfully, or decoding is finished and there is
    * nothing more to be done.
    *
-   * Note that @ref JxlDecoderProcessInput will return JXL_DEC_SUCCESS if all
-   * events that were registered with @ref JxlDecoderSubscribeEvents were
+   * Note that @ref JxlDecoderProcessInput will return ::JXL_DEC_SUCCESS if
+   * all events that were registered with @ref JxlDecoderSubscribeEvents were
    * processed, even before the end of the JPEG XL codestream.
    *
    * In this case, the return value @ref JxlDecoderReleaseInput will be the same
-   * as it was at the last signaled event. E.g. if JXL_DEC_FULL_IMAGE was
+   * as it was at the last signaled event. E.g. if ::JXL_DEC_FULL_IMAGE was
    * subscribed to, then all bytes from the end of the JPEG XL codestream
    * (including possible boxes needed for jpeg reconstruction) will be returned
    * as unprocessed.
@@ -151,14 +151,14 @@ typedef enum {
    * In most cases, @ref JxlDecoderReleaseInput will return no unprocessed bytes
    * at this event, the only exceptions are if the previously set input ended
    * within (a) the raw codestream signature, (b) the signature box, (c) a box
-   * header, or (d) the first 4 bytes of a brob, ftyp, or jxlp box. In any of
-   * these cases the number of unprocessed bytes is less than 20.
+   * header, or (d) the first 4 bytes of a `brob`, `ftyp`, or `jxlp` box. In any
+   * of these cases the number of unprocessed bytes is less than 20.
    */
   JXL_DEC_NEED_MORE_INPUT = 2,
 
   /** The decoder is able to decode a preview image and requests setting a
    * preview output buffer using @ref JxlDecoderSetPreviewOutBuffer. This occurs
-   * if @ref JXL_DEC_PREVIEW_IMAGE is requested and it is possible to decode a
+   * if ::JXL_DEC_PREVIEW_IMAGE is requested and it is possible to decode a
    * preview image from the codestream and the preview out buffer was not yet
    * set. There is maximum one preview image in a codestream.
    * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
@@ -179,13 +179,13 @@ typedef enum {
   /** The JPEG reconstruction buffer is too small for reconstructed JPEG
    * codestream to fit. @ref JxlDecoderSetJPEGBuffer must be called again to
    * make room for remaining bytes. This event may occur multiple times
-   * after @ref JXL_DEC_JPEG_RECONSTRUCTION.
+   * after ::JXL_DEC_JPEG_RECONSTRUCTION.
    */
   JXL_DEC_JPEG_NEED_MORE_OUTPUT = 6,
 
   /** The box contents output buffer is too small. @ref JxlDecoderSetBoxBuffer
    * must be called again to make room for remaining bytes. This event may occur
-   * multiple times after @ref JXL_DEC_BOX.
+   * multiple times after ::JXL_DEC_BOX.
    */
   JXL_DEC_BOX_NEED_MORE_OUTPUT = 7,
 
@@ -201,7 +201,7 @@ typedef enum {
   /** Informative event by @ref JxlDecoderProcessInput
    * "JxlDecoderProcessInput": Color encoding or ICC profile from the
    * codestream header. This event occurs max once per image and always later
-   * than @ref JXL_DEC_BASIC_INFO and earlier than any pixel data.
+   * than ::JXL_DEC_BASIC_INFO and earlier than any pixel data.
    * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
    * end of the image header (which is the start of the first frame) as
    * unprocessed.
@@ -212,7 +212,7 @@ typedef enum {
    * "JxlDecoderProcessInput": Preview image, a small frame, decoded. This
    * event can only happen if the image has a preview frame encoded. This event
    * occurs max once for the codestream and always later than @ref
-   * JXL_DEC_COLOR_ENCODING and before @ref JXL_DEC_FRAME.
+   * JXL_DEC_COLOR_ENCODING and before ::JXL_DEC_FRAME.
    * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
    * end of the preview frame as unprocessed.
    */
@@ -223,19 +223,19 @@ typedef enum {
    * JxlDecoderGetFrameHeader can be used at this point. A note on frames:
    * a JPEG XL image can have internal frames that are not intended to be
    * displayed (e.g. used for compositing a final frame), but this only returns
-   * displayed frames, unless @ref JxlDecoderSetCoalescing was set to JXL_FALSE:
-   * in that case, the individual layers are returned, without blending. Note
-   * that even when coalescing is disabled, only frames of type kRegularFrame
-   * are returned; frames of type kReferenceOnly and kLfFrame are always for
-   * internal purposes only and cannot be accessed. A displayed frame either has
-   * an animation duration or is the only or last frame in the image. This event
-   * occurs max once per displayed frame, always later than @ref
-   * JXL_DEC_COLOR_ENCODING, and always earlier than any pixel data. While
-   * JPEG XL supports encoding a single frame as the composition of multiple
-   * internal sub-frames also called frames, this event is not indicated for the
-   * internal frames.
-   * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
-   * end of the frame header (including ToC) as unprocessed.
+   * displayed frames, unless @ref JxlDecoderSetCoalescing was set to @ref
+   * JXL_FALSE "JXL_FALSE": in that case, the individual layers are returned,
+   * without blending. Note that even when coalescing is disabled, only frames
+   * of type kRegularFrame are returned; frames of type kReferenceOnly
+   * and kLfFrame are always for internal purposes only and cannot be accessed.
+   * A displayed frame either has an animation duration or is the only or last
+   * frame in the image. This event occurs max once per displayed frame, always
+   * later than ::JXL_DEC_COLOR_ENCODING, and always earlier than any pixel
+   * data. While JPEG XL supports encoding a single frame as the composition of
+   * multiple internal sub-frames also called frames, this event is not
+   * indicated for the internal frames. In this case, @ref
+   * JxlDecoderReleaseInput will return all bytes from the end of the frame
+   * header (including ToC) as unprocessed.
    */
   JXL_DEC_FRAME = 0x400,
 
@@ -246,7 +246,7 @@ typedef enum {
    * not this return status only indicates we're past this point in the
    * codestream. This event occurs max once per frame.
    * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
-   * end of the frame (or if @ref JXL_DEC_JPEG_RECONSTRUCTION is subscribed to,
+   * end of the frame (or if ::JXL_DEC_JPEG_RECONSTRUCTION is subscribed to,
    * from the end of the last box that is needed for jpeg reconstruction) as
    * unprocessed.
    */
@@ -259,9 +259,9 @@ typedef enum {
    * is set a byte stream identical to the JPEG codestream used to encode the
    * image will be written to the JPEG reconstruction buffer instead of pixels
    * to the image out buffer. This event occurs max once per image and always
-   * before @ref JXL_DEC_FULL_IMAGE.
+   * before ::JXL_DEC_FULL_IMAGE.
    * In this case, @ref JxlDecoderReleaseInput will return all bytes from the
-   * end of the 'jbrd' box as unprocessed.
+   * end of the `jbrd` box as unprocessed.
    */
   JXL_DEC_JPEG_RECONSTRUCTION = 0x2000,
 
@@ -290,8 +290,8 @@ typedef enum {
    *
    * The buffer set with @ref JxlDecoderSetBoxBuffer must be set again for each
    * next box to be obtained, or can be left unset to skip outputting this box.
-   * The output buffer contains the full box data when the next @ref JXL_DEC_BOX
-   * event or @ref JXL_DEC_SUCCESS occurs. @ref JXL_DEC_BOX occurs for all
+   * The output buffer contains the full box data when the next ::JXL_DEC_BOX
+   * event or ::JXL_DEC_SUCCESS occurs. ::JXL_DEC_BOX occurs for all
    * boxes, including non-metadata boxes such as the signature box or codestream
    * boxes. To check whether the box is a metadata type for respectively EXIF,
    * XMP or JUMBF, use @ref JxlDecoderGetBoxType and check for types "Exif",
@@ -324,26 +324,40 @@ typedef enum {
  * Setting a progressive detail with value N implies all progressive details
  * with smaller or equal value. Currently only the following level of
  * progressive detail is implemented:
- *  - kDC (which implies kFrames)
- *  - kLastPasses (which implies kDC and kFrames)
- *  - kPasses (which implies kLastPasses, kDC and kFrames)
+ *  - @ref kDC (which implies kFrames)
+ *  - @ref kLastPasses (which implies @ref kDC and @ref kFrames)
+ *  - @ref kPasses (which implies @ref kLastPasses, kDC and @ref kFrames)
  */
 typedef enum {
-  // after completed kRegularFrames
+  /**
+   * after completed kRegularFrames
+   */
   kFrames = 0,
-  // after completed DC (1:8)
+  /**
+   * after completed DC (1:8)
+   */
   kDC = 1,
-  // after completed AC passes that are the last pass for their resolution
-  // target.
+  /**
+   * after completed AC passes that are the last pass for their resolution
+   * target.
+   */
   kLastPasses = 2,
-  // after completed AC passes that are not the last pass for their resolution
-  // target.
+  /**
+   * after completed AC passes that are not the last pass for their resolution
+   * target.
+   */
   kPasses = 3,
-  // during DC frame when lower resolution are completed (1:32, 1:16)
+  /**
+   * during DC frame when lower resolution are completed (1:32, 1:16)
+   */
   kDCProgressive = 4,
-  // after completed groups
+  /**
+   * after completed groups
+   */
   kDCGroups = 5,
-  // after completed groups
+  /**
+   * after completed groups
+   */
   kGroups = 6,
 } JxlProgressiveDetail;
 
@@ -354,8 +368,8 @@ typedef enum {
  * more efficiently with @ref JxlDecoderSkipFrames. Settings such as parallel
  * runner or subscribed events are kept. After rewind, @ref
  * JxlDecoderSubscribeEvents can be used again, and it is feasible to leave out
- * events that were already handled before, such as @ref JXL_DEC_BASIC_INFO
- * and @ref JXL_DEC_COLOR_ENCODING, since they will provide the same information
+ * events that were already handled before, such as ::JXL_DEC_BASIC_INFO
+ * and ::JXL_DEC_COLOR_ENCODING, since they will provide the same information
  * as before.
  * The difference to @ref JxlDecoderReset is that some state is kept, namely
  * settings set by a call to
@@ -376,14 +390,14 @@ JXL_EXPORT void JxlDecoderRewind(JxlDecoder* dec);
  * the input, but will not output the frame events. It can be more efficient
  * when skipping frames, and even more so when using this after @ref
  * JxlDecoderRewind. If the decoder is already processing a frame (could
- * have emitted @ref JXL_DEC_FRAME but not yet @ref JXL_DEC_FULL_IMAGE), it
+ * have emitted ::JXL_DEC_FRAME but not yet ::JXL_DEC_FULL_IMAGE), it
  * starts skipping from the next frame. If the amount is larger than the amount
  * of frames remaining in the image, all remaining frames are skipped. Calling
  * this function multiple times adds the amount to skip to the already existing
  * amount.
  *
  * A frame here is defined as a frame that without skipping emits events such
- * as @ref JXL_DEC_FRAME and @ref JXL_DEC_FULL_IMAGE, frames that are internal
+ * as ::JXL_DEC_FRAME and ::JXL_DEC_FULL_IMAGE, frames that are internal
  * to the file format but are not rendered as part of an animation, or are not
  * the final still frame of a still image, are not counted.
  *
@@ -394,14 +408,14 @@ JXL_EXPORT void JxlDecoderSkipFrames(JxlDecoder* dec, size_t amount);
 
 /**
  * Skips processing the current frame. Can be called after frame processing
- * already started, signaled by a @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event,
- * but before the corresponding @ref JXL_DEC_FULL_IMAGE event. The next signaled
- * event will be another @ref JXL_DEC_FRAME, or @ref JXL_DEC_SUCCESS if there
+ * already started, signaled by a ::JXL_DEC_NEED_IMAGE_OUT_BUFFER event,
+ * but before the corresponding ::JXL_DEC_FULL_IMAGE event. The next signaled
+ * event will be another ::JXL_DEC_FRAME, or ::JXL_DEC_SUCCESS if there
  * are no more frames. If pixel data is required from the already processed part
  * of the frame, @ref JxlDecoderFlushImage must be called before this.
  *
  * @param dec decoder object
- * @return @ref JXL_DEC_SUCCESS if there is a frame to skip, and @ref
+ * @return ::JXL_DEC_SUCCESS if there is a frame to skip, and @ref
  *     JXL_DEC_ERROR if the function was not called during frame processing.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSkipCurrentFrame(JxlDecoder* dec);
@@ -415,7 +429,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSkipCurrentFrame(JxlDecoder* dec);
  *     be NULL to use the default, single-threaded, runner. A multithreaded
  *     runner should be set to reach fast performance.
  * @param parallel_runner_opaque opaque pointer for parallel_runner.
- * @return @ref JXL_DEC_SUCCESS if the runner was set, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the runner was set, ::JXL_DEC_ERROR
  *     otherwise (the previous runner remains set).
  */
 JXL_EXPORT JxlDecoderStatus
@@ -439,7 +453,7 @@ JxlDecoderSetParallelRunner(JxlDecoder* dec, JxlParallelRunner parallel_runner,
  */
 JXL_EXPORT size_t JxlDecoderSizeHintBasicInfo(const JxlDecoder* dec);
 
-/** Select for which informative events, i.e. @ref JXL_DEC_BASIC_INFO, etc., the
+/** Select for which informative events, i.e. ::JXL_DEC_BASIC_INFO, etc., the
  * decoder should return with a status. It is not required to subscribe to any
  * events, data can still be requested from the decoder as soon as it available.
  * By default, the decoder is subscribed to no events (events_wanted == 0), and
@@ -449,7 +463,7 @@ JXL_EXPORT size_t JxlDecoderSizeHintBasicInfo(const JxlDecoder* dec);
  *
  * @param dec decoder object
  * @param events_wanted bitfield of desired events.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents(JxlDecoder* dec,
                                                       int events_wanted);
@@ -459,14 +473,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents(JxlDecoder* dec,
  * indicating that the decoder must perform a rotation and/or
  * mirroring to the encoded image data.
  *
- *  - If skip_reorientation is JXL_FALSE (the default): the decoder
+ *  - If skip_reorientation is ::JXL_FALSE (the default): the decoder
  *    will apply the transformation from the orientation setting, hence
  *    rendering the image according to its specified intent. When
- *    producing a JxlBasicInfo, the decoder will always set the
+ *    producing a @ref JxlBasicInfo, the decoder will always set the
  *    orientation field to JXL_ORIENT_IDENTITY (matching the returned
  *    pixel data) and also align xsize and ysize so that they correspond
  *    to the width and the height of the returned pixel data.
- *  - If skip_reorientation is JXL_TRUE: the decoder will skip
+ *  - If skip_reorientation is ::JXL_TRUE "JXL_TRUE": the decoder will skip
  *    applying the transformation from the orientation setting, returning
  *    the image in the as-in-bitstream pixeldata orientation.
  *    This may be faster to decode since the decoder doesn't have to apply the
@@ -483,17 +497,18 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSubscribeEvents(JxlDecoder* dec,
  *
  * @param dec decoder object
  * @param skip_reorientation JXL_TRUE to enable, JXL_FALSE to disable.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus
 JxlDecoderSetKeepOrientation(JxlDecoder* dec, JXL_BOOL skip_reorientation);
 
 /**
  * Enables or disables preserving of associated alpha channels. If
- * unpremul_alpha is set to JXL_FALSE then for associated alpha channel, the
- * pixel data is returned with premultiplied colors. If it is set to JXL_TRUE,
- * The colors will be unpremultiplied based on the alpha channel. This function
- * has no effect if the image does not have an associated alpha channel.
+ * unpremul_alpha is set to ::JXL_FALSE then for associated alpha channel,
+ * the pixel data is returned with premultiplied colors. If it is set to @ref
+ * JXL_TRUE, The colors will be unpremultiplied based on the alpha channel. This
+ * function has no effect if the image does not have an associated alpha
+ * channel.
  *
  * By default, this option is disabled, and the returned pixel data "as is".
  *
@@ -501,20 +516,20 @@ JxlDecoderSetKeepOrientation(JxlDecoder* dec, JXL_BOOL skip_reorientation);
  *
  * @param dec decoder object
  * @param unpremul_alpha JXL_TRUE to enable, JXL_FALSE to disable.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus
 JxlDecoderSetUnpremultiplyAlpha(JxlDecoder* dec, JXL_BOOL unpremul_alpha);
 
 /** Enables or disables rendering spot colors. By default, spot colors
  * are rendered, which is OK for viewing the decoded image. If render_spotcolors
- * is JXL_FALSE, then spot colors are not rendered, and have to be retrieved
- * separately using @ref JxlDecoderSetExtraChannelBuffer. This is useful for
- * e.g. printing applications.
+ * is ::JXL_FALSE, then spot colors are not rendered, and have to be
+ * retrieved separately using @ref JxlDecoderSetExtraChannelBuffer. This is
+ * useful for e.g. printing applications.
  *
  * @param dec decoder object
  * @param render_spotcolors JXL_TRUE to enable (default), JXL_FALSE to disable.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus
 JxlDecoderSetRenderSpotcolors(JxlDecoder* dec, JXL_BOOL render_spotcolors);
@@ -530,7 +545,7 @@ JxlDecoderSetRenderSpotcolors(JxlDecoder* dec, JXL_BOOL render_spotcolors);
  * @param dec decoder object
  * @param coalescing JXL_TRUE to enable coalescing (default), JXL_FALSE to
  *     disable it.
- * @return @ref JXL_DEC_SUCCESS if no error, @ref JXL_DEC_ERROR otherwise.
+ * @return ::JXL_DEC_SUCCESS if no error, ::JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetCoalescing(JxlDecoder* dec,
                                                     JXL_BOOL coalescing);
@@ -547,32 +562,32 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetCoalescing(JxlDecoder* dec,
  *
  * The returned status indicates whether the decoder needs more input bytes, or
  * more output buffer for a certain type of output data. No matter what the
- * returned status is (other than @ref JXL_DEC_ERROR), new information, such
+ * returned status is (other than ::JXL_DEC_ERROR), new information, such
  * as @ref JxlDecoderGetBasicInfo, may have become available after this call.
- * When the return value is not @ref JXL_DEC_ERROR or @ref JXL_DEC_SUCCESS, the
+ * When the return value is not ::JXL_DEC_ERROR or ::JXL_DEC_SUCCESS, the
  * decoding requires more @ref JxlDecoderProcessInput calls to continue.
  *
  * @param dec decoder object
- * @return @ref JXL_DEC_SUCCESS when decoding finished and all events handled.
+ * @return ::JXL_DEC_SUCCESS when decoding finished and all events handled.
  *     If you still have more unprocessed input data anyway, then you can still
  *     continue by using @ref JxlDecoderSetInput and calling @ref
  *     JxlDecoderProcessInput again, similar to handling @ref
- *     JXL_DEC_NEED_MORE_INPUT. @ref JXL_DEC_SUCCESS can occur instead of @ref
+ *     JXL_DEC_NEED_MORE_INPUT. ::JXL_DEC_SUCCESS can occur instead of @ref
  *     JXL_DEC_NEED_MORE_INPUT when, for example, the input data ended right at
  *     the boundary of a box of the container format, all essential codestream
  *     boxes were already decoded, but extra metadata boxes are still present in
  *     the next data. @ref JxlDecoderProcessInput cannot return success if all
  *     codestream boxes have not been seen yet.
- * @return @ref JXL_DEC_ERROR when decoding failed, e.g. invalid codestream.
+ * @return ::JXL_DEC_ERROR when decoding failed, e.g. invalid codestream.
  *     TODO(lode): document the input data mechanism
- * @return @ref JXL_DEC_NEED_MORE_INPUT when more input data is necessary.
- * @return @ref JXL_DEC_BASIC_INFO when basic info such as image dimensions is
+ * @return ::JXL_DEC_NEED_MORE_INPUT when more input data is necessary.
+ * @return ::JXL_DEC_BASIC_INFO when basic info such as image dimensions is
  *     available and this informative event is subscribed to.
- * @return @ref JXL_DEC_COLOR_ENCODING when color profile information is
+ * @return ::JXL_DEC_COLOR_ENCODING when color profile information is
  *     available and this informative event is subscribed to.
- * @return @ref JXL_DEC_PREVIEW_IMAGE when preview pixel information is
+ * @return ::JXL_DEC_PREVIEW_IMAGE when preview pixel information is
  *     available and output in the preview buffer.
- * @return @ref JXL_DEC_FULL_IMAGE when all pixel information at highest detail
+ * @return ::JXL_DEC_FULL_IMAGE when all pixel information at highest detail
  *     is available and has been output in the pixel buffer.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderProcessInput(JxlDecoder* dec);
@@ -588,8 +603,8 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderProcessInput(JxlDecoder* dec);
  * @param dec decoder object
  * @param data pointer to next bytes to read from
  * @param size amount of bytes available starting from data
- * @return @ref JXL_DEC_ERROR if input was already set without releasing or @ref
- *     JxlDecoderCloseInput was already called, @ref JXL_DEC_SUCCESS otherwise.
+ * @return ::JXL_DEC_ERROR if input was already set without releasing or @ref
+ *     JxlDecoderCloseInput was already called, ::JXL_DEC_SUCCESS otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetInput(JxlDecoder* dec,
                                                const uint8_t* data,
@@ -602,17 +617,17 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetInput(JxlDecoder* dec,
  * whenever any input is already set and new input needs to be added with @ref
  * JxlDecoderSetInput, but is not required before @ref JxlDecoderDestroy or @ref
  * JxlDecoderReset. Calling @ref JxlDecoderReleaseInput when no input is set is
- * not an error and returns 0.
+ * not an error and returns `0`.
  *
  * @param dec decoder object
  * @return The amount of bytes the decoder has not yet processed that are still
- *     remaining in the data set by @ref JxlDecoderSetInput, or 0 if no input is
- *     set or @ref JxlDecoderReleaseInput was already called. For a next call
- *     to @ref JxlDecoderProcessInput, the buffer must start with these
- *     unprocessed bytes. From this value it is possible to infer the position
- *     of certain JPEG XL codestream elements (e.g. end of headers, frame
- *     start/end). See the documentation of individual values of @ref
- *     JxlDecoderStatus for more information.
+ *     remaining in the data set by @ref JxlDecoderSetInput, or `0` if no input
+ * is set or @ref JxlDecoderReleaseInput was already called. For a next call to
+ * @ref JxlDecoderProcessInput, the buffer must start with these unprocessed
+ * bytes. From this value it is possible to infer the position of certain JPEG
+ * XL codestream elements (e.g. end of headers, frame start/end). See the
+ * documentation of individual values of @ref JxlDecoderStatus for more
+ * information.
  */
 JXL_EXPORT size_t JxlDecoderReleaseInput(JxlDecoder* dec);
 
@@ -621,9 +636,9 @@ JXL_EXPORT size_t JxlDecoderReleaseInput(JxlDecoder* dec);
  * will be called. This function allows the decoder to determine correctly if it
  * should return success, need more input or error in certain cases. For
  * backwards compatibility with a previous version of the API, using this
- * function is optional when not using the @ref JXL_DEC_BOX event (the decoder
+ * function is optional when not using the ::JXL_DEC_BOX event (the decoder
  * is able to determine the end of the image frames without marking the end),
- * but using this function is required when using @ref JXL_DEC_BOX for getting
+ * but using this function is required when using ::JXL_DEC_BOX for getting
  * metadata box contents. This function does not replace @ref
  * JxlDecoderReleaseInput, that function should still be called if its return
  * value is needed.
@@ -643,8 +658,8 @@ JXL_EXPORT void JxlDecoderCloseInput(JxlDecoder* dec);
  * @param dec decoder object
  * @param info struct to copy the information into, or NULL to only check
  *     whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- *     JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ *     JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR
  *     in case of other error conditions.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetBasicInfo(const JxlDecoder* dec,
@@ -652,14 +667,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetBasicInfo(const JxlDecoder* dec,
 
 /**
  * Outputs information for extra channel at the given index. The index must be
- * smaller than num_extra_channels in the associated JxlBasicInfo.
+ * smaller than num_extra_channels in the associated @ref JxlBasicInfo.
  *
  * @param dec decoder object
  * @param index index of the extra channel to query.
  * @param info struct to copy the information into, or NULL to only check
  *     whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- *     JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ *     JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR
  *     in case of other error conditions.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelInfo(
@@ -667,16 +682,16 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelInfo(
 
 /**
  * Outputs name for extra channel at the given index in UTF-8. The index must be
- * smaller than num_extra_channels in the associated JxlBasicInfo. The buffer
- * for name must have at least name_length + 1 bytes allocated, gotten from
- * the associated JxlExtraChannelInfo.
+ * smaller than `num_extra_channels` in the associated @ref JxlBasicInfo. The
+ * buffer for name must have at least `name_length + 1` bytes allocated, gotten
+ * from the associated @ref JxlExtraChannelInfo.
  *
  * @param dec decoder object
  * @param index index of the extra channel to query.
  * @param name buffer to copy the name into
  * @param size size of the name buffer in bytes
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- *     JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ *     JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR
  *     in case of other error conditions.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelName(const JxlDecoder* dec,
@@ -719,7 +734,7 @@ typedef enum {
  *    problematic, in that: while ICC profiles can encode a transfer function
  *    that happens to approximate those of PQ and HLG (HLG for only one given
  *    system gamma at a time, and necessitating a 3D LUT if gamma is to be
- *    different from 1), they cannot (before ICCv4.4) semantically signal that
+ *    different from `1`), they cannot (before ICCv4.4) semantically signal that
  *    this is the color space that they represent. Therefore, they will
  *    typically not actually be interpreted as representing an HDR color space.
  *    This is especially detrimental to PQ which will then be interpreted as if
@@ -741,8 +756,8 @@ typedef enum {
  *     or the color profile of the decoded pixels.
  * @param color_encoding struct to copy the information into, or NULL to only
  *     check whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the data is available and returned, @ref
- *     JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * @return ::JXL_DEC_SUCCESS if the data is available and returned, @ref
+ *     JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR in
  *     case the encoded structured color profile does not exist in the
  *     codestream.
  */
@@ -766,10 +781,10 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsEncodedProfile(
  *     or the color profile of the decoded pixels.
  * @param size variable to output the size into, or NULL to only check the
  *     return status.
- * @return @ref JXL_DEC_SUCCESS if the ICC profile is available, @ref
+ * @return ::JXL_DEC_SUCCESS if the ICC profile is available, @ref
  *     JXL_DEC_NEED_MORE_INPUT if the decoder has not yet received enough
  *     input data to determine whether an ICC profile is available or what its
- *     size is, @ref JXL_DEC_ERROR in case the ICC profile is not available and
+ *     size is, ::JXL_DEC_ERROR in case the ICC profile is not available and
  *     cannot be generated.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetICCProfileSize(
@@ -785,8 +800,8 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetICCProfileSize(
  *     or the color profile of the decoded pixels.
  * @param icc_profile buffer to copy the ICC profile into
  * @param size size of the icc_profile buffer in bytes
- * @return @ref JXL_DEC_SUCCESS if the profile was successfully returned is
- *     available, @ref JXL_DEC_NEED_MORE_INPUT if not yet available, @ref
+ * @return ::JXL_DEC_SUCCESS if the profile was successfully returned is
+ *     available, ::JXL_DEC_NEED_MORE_INPUT if not yet available, @ref
  *     JXL_DEC_ERROR if the profile doesn't exist or the output size is not
  *     large enough.
  */
@@ -801,7 +816,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetColorAsICCProfile(
  *
  * @param dec decoder object
  * @param color_encoding the default color encoding to set
- * @return @ref JXL_DEC_SUCCESS if the preference was set successfully, @ref
+ * @return ::JXL_DEC_SUCCESS if the preference was set successfully, @ref
  *     JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreferredColorProfile(
@@ -814,7 +829,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreferredColorProfile(
  * change from version to version.
  * @param dec decoder object
  * @param desired_intensity_target the intended target peak luminance
- * @return @ref JXL_DEC_SUCCESS if the preference was set successfully, @ref
+ * @return ::JXL_DEC_SUCCESS if the preference was set successfully, @ref
  * JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget(
@@ -823,7 +838,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget(
 /**
  * Sets the desired output color profile of the decoded image either from a
  * color encoding or an ICC profile. Valid calls of this function have either @c
- * color_encoding or @c icc_data set to NULL and @c icc_size must be 0 if and
+ * color_encoding or @c icc_data set to NULL and @c icc_size must be `0` if and
  * only if @c icc_data is NULL.
  *
  * Depending on whether a color management system (CMS) has been set the
@@ -848,17 +863,17 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDesiredIntensityTarget(
  * If called with an ICC profile (after a call to @ref JxlDecoderSetCms), the
  * ICC profile has to be a valid RGB or grayscale color profile.
  *
- * Can only be set after the @ref JXL_DEC_COLOR_ENCODING event occurred and
+ * Can only be set after the ::JXL_DEC_COLOR_ENCODING event occurred and
  * before any other event occurred, and should be used before getting
- * JXL_COLOR_PROFILE_TARGET_DATA.
+ * ::JXL_COLOR_PROFILE_TARGET_DATA.
  *
- * This function must not be called before JxlDecoderSetCms.
+ * This function must not be called before @ref JxlDecoderSetCms.
  *
  * @param dec decoder orbject
  * @param color_encoding the output color encoding
  * @param icc_data bytes of the icc profile
  * @param icc_size size of the icc profile in bytes
- * @return @ref JXL_DEC_SUCCESS if the color profile was set successfully, @ref
+ * @return ::JXL_DEC_SUCCESS if the color profile was set successfully, @ref
  *     JXL_DEC_ERROR otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetOutputColorProfile(
@@ -891,7 +906,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetCms(JxlDecoder* dec,
  * @param dec decoder object
  * @param format format of pixels
  * @param size output value, buffer size in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     information not available yet.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderPreviewOutBufferSize(
@@ -901,15 +916,15 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderPreviewOutBufferSize(
  * Sets the buffer to write the small resolution preview image
  * to. The size of the buffer must be at least as large as given by @ref
  * JxlDecoderPreviewOutBufferSize. The buffer follows the format described
- * by JxlPixelFormat. The preview image dimensions are given by the
- * JxlPreviewHeader. The buffer is owned by the caller.
+ * by @ref JxlPixelFormat. The preview image dimensions are given by the
+ * @ref JxlPreviewHeader. The buffer is owned by the caller.
  *
  * @param dec decoder object
  * @param format format of pixels. Object owned by user and its contents are
  *     copied internally.
  * @param buffer buffer type to output the pixel data to
  * @param size size of buffer in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     size too small.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreviewOutBuffer(
@@ -917,14 +932,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetPreviewOutBuffer(
 
 /**
  * Outputs the information from the frame, such as duration when have_animation.
- * This function can be called when @ref JXL_DEC_FRAME occurred for the current
+ * This function can be called when ::JXL_DEC_FRAME occurred for the current
  * frame, even when have_animation in the JxlBasicInfo is JXL_FALSE.
  *
  * @param dec decoder object
  * @param header struct to copy the information into, or NULL to only check
  *     whether the information is available through the return value.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- *     JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ *     JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR in
  *     case of other error conditions.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameHeader(const JxlDecoder* dec,
@@ -932,14 +947,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameHeader(const JxlDecoder* dec,
 
 /**
  * Outputs name for the current frame. The buffer for name must have at least
- * name_length + 1 bytes allocated, gotten from the associated JxlFrameHeader.
+ * `name_length + 1` bytes allocated, gotten from the associated JxlFrameHeader.
  *
  * @param dec decoder object
  * @param name buffer to copy the name into
  * @param size size of the name buffer in bytes, including zero termination
- *    character, so this must be at least JxlFrameHeader.name_length + 1.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref
- *     JXL_DEC_NEED_MORE_INPUT if not yet available, @ref JXL_DEC_ERROR in
+ *    character, so this must be at least @ref JxlFrameHeader.name_length + 1.
+ * @return ::JXL_DEC_SUCCESS if the value is available, @ref
+ *     JXL_DEC_NEED_MORE_INPUT if not yet available, ::JXL_DEC_ERROR in
  *     case of other error conditions.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameName(const JxlDecoder* dec,
@@ -947,15 +962,15 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetFrameName(const JxlDecoder* dec,
 
 /**
  * Outputs the blend information for the current frame for a specific extra
- * channel. This function can be called when @ref JXL_DEC_FRAME occurred for the
- * current frame, even when have_animation in the JxlBasicInfo is JXL_FALSE.
- * This information is only useful if coalescing is disabled; otherwise the
- * decoder will have performed blending already.
+ * channel. This function can be called when ::JXL_DEC_FRAME occurred for the
+ * current frame, even when have_animation in the @ref JxlBasicInfo is @ref
+ * JXL_FALSE. This information is only useful if coalescing is disabled;
+ * otherwise the decoder will have performed blending already.
  *
  * @param dec decoder object
  * @param index the index of the extra channel
  * @param blend_info struct to copy the information into
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelBlendInfo(
     const JxlDecoder* dec, size_t index, JxlBlendInfo* blend_info);
@@ -965,14 +980,14 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetExtraChannelBlendInfo(
  * given format. This is the buffer for @ref JxlDecoderSetImageOutBuffer.
  * Requires that the basic image information is available in the decoder in the
  * case of coalescing enabled (default). In case coalescing is disabled, this
- * can only be called after the @ref JXL_DEC_FRAME event occurs. In that case,
+ * can only be called after the ::JXL_DEC_FRAME event occurs. In that case,
  * it will return the size required to store the possibly cropped frame (which
  * can be larger or smaller than the image dimensions).
  *
  * @param dec decoder object
  * @param format format of the pixels.
  * @param size output value, buffer size in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     information not available yet.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderImageOutBufferSize(
@@ -980,18 +995,18 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderImageOutBufferSize(
 
 /**
  * Sets the buffer to write the full resolution image to. This can be set when
- * the @ref JXL_DEC_FRAME event occurs, must be set when the @ref
+ * the ::JXL_DEC_FRAME event occurs, must be set when the @ref
  * JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs, and applies only for the
  * current frame. The size of the buffer must be at least as large as given
  * by @ref JxlDecoderImageOutBufferSize. The buffer follows the format described
- * by JxlPixelFormat. The buffer is owned by the caller.
+ * by @ref JxlPixelFormat. The buffer is owned by the caller.
  *
  * @param dec decoder object
  * @param format format of the pixels. Object owned by user and its contents
  *     are copied internally.
  * @param buffer buffer type to output the pixel data to
  * @param size size of buffer in bytes
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     size too small.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetImageOutBuffer(
@@ -1062,15 +1077,15 @@ typedef void (*JxlImageOutDestroyCallback)(void* run_opaque);
 
 /**
  * Sets pixel output callback. This is an alternative to @ref
- * JxlDecoderSetImageOutBuffer. This can be set when the @ref JXL_DEC_FRAME
- * event occurs, must be set when the @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event
+ * JxlDecoderSetImageOutBuffer. This can be set when the ::JXL_DEC_FRAME
+ * event occurs, must be set when the ::JXL_DEC_NEED_IMAGE_OUT_BUFFER event
  * occurs, and applies only for the current frame. Only one of @ref
  * JxlDecoderSetImageOutBuffer or @ref JxlDecoderSetImageOutCallback may be used
  * for the same frame, not both at the same time.
  *
  * The callback will be called multiple times, to receive the image
  * data in small chunks. The callback receives a horizontal stripe of pixel
- * data, 1 pixel high, xsize pixels wide, called a scanline. The xsize here is
+ * data, `1` pixel high, xsize pixels wide, called a scanline. The xsize here is
  * not the same as the full image width, the scanline may be a partial section,
  * and xsize may differ between calls. The user can then process and/or copy the
  * partial scanline to an image buffer. The callback may be called
@@ -1099,7 +1114,7 @@ typedef void (*JxlImageOutDestroyCallback)(void* run_opaque);
  *     data.
  * @param opaque optional user data, which will be passed on to the callback,
  *     may be NULL.
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such
  *     as @ref JxlDecoderSetImageOutBuffer already set.
  */
 JXL_EXPORT JxlDecoderStatus
@@ -1122,7 +1137,7 @@ JxlDecoderSetImageOutCallback(JxlDecoder* dec, const JxlPixelFormat* format,
  * @param init_opaque optional user data passed to @c init_callback, may be NULL
  *     (unlike the return value from @c init_callback which may only be NULL if
  *     initialization failed).
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such
  *     as @ref JxlDecoderSetImageOutBuffer having already been called.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetMultithreadedImageOutCallback(
@@ -1137,12 +1152,12 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetMultithreadedImageOutCallback(
  *
  * @param dec decoder object
  * @param format format of the pixels. The num_channels value is ignored and is
- *     always treated to be 1.
+ *     always treated to be `1`.
  * @param size output value, buffer size in bytes
  * @param index which extra channel to get, matching the index used in @ref
  *     JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in
- *     the associated JxlBasicInfo.
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ *     the associated @ref JxlBasicInfo.
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     information not available yet or invalid index.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize(
@@ -1151,13 +1166,13 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize(
 
 /**
  * Sets the buffer to write an extra channel to. This can be set when
- * the @ref JXL_DEC_FRAME or @ref JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs,
+ * the ::JXL_DEC_FRAME or ::JXL_DEC_NEED_IMAGE_OUT_BUFFER event occurs,
  * and applies only for the current frame. The size of the buffer must be at
  * least as large as given by @ref JxlDecoderExtraChannelBufferSize. The buffer
- * follows the format described by JxlPixelFormat, but where num_channels is 1.
- * The buffer is owned by the caller. The amount of extra channels is given by
- * the num_extra_channels field in the associated JxlBasicInfo, and the
- * information of individual extra channels can be queried with @ref
+ * follows the format described by @ref JxlPixelFormat, but where num_channels
+ * is `1`. The buffer is owned by the caller. The amount of extra channels is
+ * given by the num_extra_channels field in the associated @ref JxlBasicInfo,
+ * and the information of individual extra channels can be queried with @ref
  * JxlDecoderGetExtraChannelInfo. To get multiple extra channels, this function
  * must be called multiple times, once for each wanted index. Not all images
  * have extra channels. The alpha channel is an extra channel and can be gotten
@@ -1170,13 +1185,13 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderExtraChannelBufferSize(
  * @param dec decoder object
  * @param format format of the pixels. Object owned by user and its contents
  *     are copied internally. The num_channels value is ignored and is always
- *     treated to be 1.
+ *     treated to be `1`.
  * @param buffer buffer type to output the pixel data to
  * @param size size of buffer in bytes
  * @param index which extra channel to get, matching the index used in @ref
  *     JxlDecoderGetExtraChannelInfo. Must be smaller than num_extra_channels in
- *     the associated JxlBasicInfo.
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ *     the associated @ref JxlBasicInfo.
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     size too small or invalid index.
  */
 JXL_EXPORT JxlDecoderStatus
@@ -1197,8 +1212,8 @@ JxlDecoderSetExtraChannelBuffer(JxlDecoder* dec, const JxlPixelFormat* format,
  * @param dec decoder object
  * @param data pointer to next bytes to write to
  * @param size amount of bytes available starting from data
- * @return @ref JXL_DEC_ERROR if output buffer was already set and @ref
- *     JxlDecoderReleaseJPEGBuffer was not called on it, @ref JXL_DEC_SUCCESS
+ * @return ::JXL_DEC_ERROR if output buffer was already set and @ref
+ *     JxlDecoderReleaseJPEGBuffer was not called on it, ::JXL_DEC_SUCCESS
  *     otherwise
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetJPEGBuffer(JxlDecoder* dec,
@@ -1213,11 +1228,11 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetJPEGBuffer(JxlDecoder* dec,
  * JxlDecoderDestroy or @ref JxlDecoderReset.
  *
  * Calling @ref JxlDecoderReleaseJPEGBuffer when no buffer is set is
- * not an error and returns 0.
+ * not an error and returns `0`.
  *
  * @param dec decoder object
  * @return the amount of bytes the decoder has not yet written to of the data
- *     set by @ref JxlDecoderSetJPEGBuffer, or 0 if no buffer is set or @ref
+ *     set by @ref JxlDecoderSetJPEGBuffer, or `0` if no buffer is set or @ref
  *     JxlDecoderReleaseJPEGBuffer was already called.
  */
 JXL_EXPORT size_t JxlDecoderReleaseJPEGBuffer(JxlDecoder* dec);
@@ -1233,15 +1248,15 @@ JXL_EXPORT size_t JxlDecoderReleaseJPEGBuffer(JxlDecoder* dec);
  * JxlDecoderReleaseBoxBuffer, bytes that the decoder has already output
  * should not be included, only the remaining bytes output must be set.
  *
- * The @ref JxlDecoderReleaseBoxBuffer must be used at the next @ref JXL_DEC_BOX
- * event or final @ref JXL_DEC_SUCCESS event to compute the size of the output
+ * The @ref JxlDecoderReleaseBoxBuffer must be used at the next ::JXL_DEC_BOX
+ * event or final ::JXL_DEC_SUCCESS event to compute the size of the output
  * box bytes.
  *
  * @param dec decoder object
  * @param data pointer to next bytes to write to
  * @param size amount of bytes available starting from data
- * @return @ref JXL_DEC_ERROR if output buffer was already set and @ref
- *     JxlDecoderReleaseBoxBuffer was not called on it, @ref JXL_DEC_SUCCESS
+ * @return ::JXL_DEC_ERROR if output buffer was already set and @ref
+ *     JxlDecoderReleaseBoxBuffer was not called on it, ::JXL_DEC_SUCCESS
  *     otherwise
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetBoxBuffer(JxlDecoder* dec,
@@ -1256,11 +1271,11 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetBoxBuffer(JxlDecoder* dec,
  * JxlDecoderDestroy or @ref JxlDecoderReset.
  *
  * Calling @ref JxlDecoderReleaseBoxBuffer when no buffer is set is
- * not an error and returns 0.
+ * not an error and returns `0`.
  *
  * @param dec decoder object
  * @return the amount of bytes the decoder has not yet written to of the data
- *     set by @ref JxlDecoderSetBoxBuffer, or 0 if no buffer is set or @ref
+ *     set by @ref JxlDecoderSetBoxBuffer, or `0` if no buffer is set or @ref
  *     JxlDecoderReleaseBoxBuffer was already called.
  */
 JXL_EXPORT size_t JxlDecoderReleaseBoxBuffer(JxlDecoder* dec);
@@ -1274,23 +1289,23 @@ JXL_EXPORT size_t JxlDecoderReleaseBoxBuffer(JxlDecoder* dec);
  * finished.
  *
  * The default mode is raw. This setting can only be changed before decoding, or
- * directly after a @ref JXL_DEC_BOX event, and is remembered until the decoder
+ * directly after a ::JXL_DEC_BOX event, and is remembered until the decoder
  * is reset or destroyed.
  *
  * Enabling decompressed mode requires Brotli support from the library.
  *
  * @param dec decoder object
- * @param decompress JXL_TRUE to transparently decompress, JXL_FALSE to get
- *     boxes in raw mode.
- * @return @ref JXL_DEC_ERROR if decompressed mode is set and Brotli is not
- *     available, @ref JXL_DEC_SUCCESS otherwise.
+ * @param decompress ::JXL_TRUE to transparently decompress, ::JXL_FALSE
+ * to get boxes in raw mode.
+ * @return ::JXL_DEC_ERROR if decompressed mode is set and Brotli is not
+ *     available, ::JXL_DEC_SUCCESS otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes(JxlDecoder* dec,
                                                          JXL_BOOL decompress);
 
 /**
- * Outputs the type of the current box, after a @ref JXL_DEC_BOX event occurred,
- * as 4 characters without null termination character. In case of a compressed
+ * Outputs the type of the current box, after a ::JXL_DEC_BOX event occurred,
+ * as `4` characters without null termination character. In case of a compressed
  * "brob" box, this will return "brob" if the decompressed argument is
  * JXL_FALSE, or the underlying box type if the decompressed argument is
  * JXL_TRUE.
@@ -1306,15 +1321,15 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes(JxlDecoder* dec,
  *  - "xml ": a box with XML data, in particular XMP metadata.
  *  - "jumb": a JUMBF superbox (JPEG Universal Metadata Box Format, ISO/IEC
  *    19566-5).
- *  - "JXL ": mandatory signature box, must come first, 12 bytes long including
- *    the box header
- *  - "ftyp": a second mandatory signature box, must come second, 20 bytes long
- *    including the box header
- *  - "jxll": a JXL level box. This indicates if the codestream is level 5 or
- *    level 10 compatible. If not present, it is level 5. Level 10 allows more
- *    features such as very high image resolution and bit-depths above 16 bits
- *    per channel. Added automatically by the encoder when
- *    JxlEncoderSetCodestreamLevel is used
+ *  - "JXL ": mandatory signature box, must come first, `12` bytes long
+ * including the box header
+ *  - "ftyp": a second mandatory signature box, must come second, `20` bytes
+ * long including the box header
+ *  - "jxll": a JXL level box. This indicates if the codestream is level `5` or
+ *    level `10` compatible. If not present, it is level `5`. Level `10` allows
+ * more features such as very high image resolution and bit-depths above `16`
+ * bits per channel. Added automatically by the encoder when
+ *    @ref JxlEncoderSetCodestreamLevel is used
  *  - "jxlc": a box with the image codestream, in case the codestream is not
  *    split across multiple boxes. The codestream contains the JPEG XL image
  *    itself, including the basic info such as image dimensions, ICC color
@@ -1350,7 +1365,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderSetDecompressBoxes(JxlDecoder* dec,
  * @param type buffer to copy the type into
  * @param decompressed which box type to get: JXL_FALSE to get the raw box type,
  *     which can be "brob", JXL_TRUE, get the underlying box type.
- * @return @ref JXL_DEC_SUCCESS if the value is available, @ref JXL_DEC_ERROR if
+ * @return ::JXL_DEC_SUCCESS if the value is available, ::JXL_DEC_ERROR if
  *     not, for example the JXL file does not use the container format.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxType(JxlDecoder* dec,
@@ -1363,13 +1378,29 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxType(JxlDecoder* dec,
  *
  * @param dec decoder object
  * @param size raw size of the box in bytes
- * @return @ref JXL_DEC_ERROR if no box size is available, @ref JXL_DEC_SUCCESS
+ * @return ::JXL_DEC_ERROR if no box size is available, ::JXL_DEC_SUCCESS
  *     otherwise.
  */
 JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeRaw(const JxlDecoder* dec,
                                                     uint64_t* size);
 
 /**
+ * Returns the size of the contents of a box, after the @ref
+ * JXL_DEC_BOX event. This does not include any of the headers of the box. For
+ * compressed "brob" boxes, this is the size of the compressed content. Even
+ * when @ref JxlDecoderSetDecompressBoxes is enabled, the return value of
+ * function does not change, and the decompressed size is not known before it
+ * has already been decompressed and output.
+ *
+ * @param dec decoder object
+ * @param size size of the payload of the box in bytes
+ * @return @ref JXL_DEC_ERROR if no box size is available, @ref JXL_DEC_SUCCESS
+ *     otherwise.
+ */
+JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeContents(const JxlDecoder* dec,
+                                                         uint64_t* size);
+
+/**
  * Configures at which progressive steps in frame decoding these @ref
  * JXL_DEC_FRAME_PROGRESSION event occurs. The default value for the level
  * of detail if this function is never called is `kDC`.
@@ -1377,7 +1408,7 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderGetBoxSizeRaw(const JxlDecoder* dec,
  * @param dec decoder object
  * @param detail at which level of detail to trigger @ref
  *     JXL_DEC_FRAME_PROGRESSION
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     an invalid value for the progressive detail.
  */
 JXL_EXPORT JxlDecoderStatus
@@ -1385,11 +1416,11 @@ JxlDecoderSetProgressiveDetail(JxlDecoder* dec, JxlProgressiveDetail detail);
 
 /**
  * Returns the intended downsampling ratio for the progressive frame produced
- * by @ref JxlDecoderFlushImage after the latest @ref JXL_DEC_FRAME_PROGRESSION
+ * by @ref JxlDecoderFlushImage after the latest ::JXL_DEC_FRAME_PROGRESSION
  * event.
  *
  * @param dec decoder object
- * @return The intended downsampling ratio, can be 1, 2, 4 or 8.
+ * @return The intended downsampling ratio, can be `1`, `2`, `4` or `8`.
  */
 JXL_EXPORT size_t JxlDecoderGetIntendedDownsamplingRatio(JxlDecoder* dec);
 
@@ -1399,12 +1430,12 @@ JXL_EXPORT size_t JxlDecoderGetIntendedDownsamplingRatio(JxlDecoder* dec);
  * JxlDecoderSetImageOutBuffer will contain partial image data.
  *
  * Can be called when @ref JxlDecoderProcessInput returns @ref
- * JXL_DEC_NEED_MORE_INPUT, after the @ref JXL_DEC_FRAME event already occurred
- * and before the @ref JXL_DEC_FULL_IMAGE event occurred for a frame.
+ * JXL_DEC_NEED_MORE_INPUT, after the ::JXL_DEC_FRAME event already occurred
+ * and before the ::JXL_DEC_FULL_IMAGE event occurred for a frame.
  *
  * @param dec decoder object
- * @return @ref JXL_DEC_SUCCESS if image data was flushed to the output buffer,
- *     or @ref JXL_DEC_ERROR when no flush was done, e.g. if not enough image
+ * @return ::JXL_DEC_SUCCESS if image data was flushed to the output buffer,
+ *     or ::JXL_DEC_ERROR when no flush was done, e.g. if not enough image
  *     data was available yet even for flush, or no output buffer was set yet.
  *     This error is not fatal, it only indicates no flushed image is available
  *     right now. Regular decoding can still be performed.
@@ -1416,11 +1447,11 @@ JXL_EXPORT JxlDecoderStatus JxlDecoderFlushImage(JxlDecoder* dec);
  *
  * Can be called after @ref JxlDecoderSetImageOutBuffer or @ref
  * JxlDecoderSetImageOutCallback. For float pixel data types, only the default
- * @ref JXL_BIT_DEPTH_FROM_PIXEL_FORMAT setting is supported.
+ * ::JXL_BIT_DEPTH_FROM_PIXEL_FORMAT setting is supported.
  *
  * @param dec decoder object
  * @param bit_depth the bit depth setting of the pixel output
- * @return @ref JXL_DEC_SUCCESS on success, @ref JXL_DEC_ERROR on error, such as
+ * @return ::JXL_DEC_SUCCESS on success, ::JXL_DEC_ERROR on error, such as
  *     incompatible custom bit depth and pixel data type.
  */
 JXL_EXPORT JxlDecoderStatus
diff --git a/third_party/jpeg-xl/lib/include/jxl/encode.h b/third_party/jpeg-xl/lib/include/jxl/encode.h
index 2a87821f06..bb11dd7572 100644
--- a/third_party/jpeg-xl/lib/include/jxl/encode.h
+++ b/third_party/jpeg-xl/lib/include/jxl/encode.h
@@ -41,8 +41,8 @@ JXL_EXPORT uint32_t JxlEncoderVersion(void);
 /**
  * Opaque structure that holds the JPEG XL encoder.
  *
- * Allocated and initialized with JxlEncoderCreate().
- * Cleaned up and deallocated with JxlEncoderDestroy().
+ * Allocated and initialized with @ref JxlEncoderCreate().
+ * Cleaned up and deallocated with @ref JxlEncoderDestroy().
  */
 typedef struct JxlEncoderStruct JxlEncoder;
 
@@ -50,9 +50,9 @@ typedef struct JxlEncoderStruct JxlEncoder;
  * Settings and metadata for a single image frame. This includes encoder options
  * for a frame such as compression quality and speed.
  *
- * Allocated and initialized with JxlEncoderFrameSettingsCreate().
+ * Allocated and initialized with @ref JxlEncoderFrameSettingsCreate().
  * Cleaned up and deallocated when the encoder is destroyed with
- * JxlEncoderDestroy().
+ * @ref JxlEncoderDestroy().
  */
 typedef struct JxlEncoderFrameSettingsStruct JxlEncoderFrameSettings;
 
@@ -126,7 +126,7 @@ typedef enum {
 typedef enum {
   /** Sets encoder effort/speed level without affecting decoding speed. Valid
    * values are, from faster to slower speed: 1:lightning 2:thunder 3:falcon
-   * 4:cheetah 5:hare 6:wombat 7:squirrel 8:kitten 9:tortoise.
+   * 4:cheetah 5:hare 6:wombat 7:squirrel 8:kitten 9:tortoise 10:glacier.
    * Default: squirrel (7).
    */
   JXL_ENC_FRAME_SETTING_EFFORT = 0,
@@ -145,7 +145,7 @@ typedef enum {
    */
   JXL_ENC_FRAME_SETTING_RESAMPLING = 2,
 
-  /** Similar to JXL_ENC_FRAME_SETTING_RESAMPLING, but for extra channels.
+  /** Similar to ::JXL_ENC_FRAME_SETTING_RESAMPLING, but for extra channels.
    * Integer option, use -1 for the default behavior (depends on encoder
    * implementation), 1 for no downsampling (1x1), 2 for 2x2 downsampling, 4 for
    * 4x4 downsampling, 8 for 8x8 downsampling.
@@ -158,7 +158,7 @@ typedef enum {
    * downsampled resolution, not the full image resolution. The downsampled
    * resolution is given by ceil(xsize / resampling), ceil(ysize / resampling)
    * with xsize and ysize the dimensions given in the basic info, and resampling
-   * the factor set with @ref JXL_ENC_FRAME_SETTING_RESAMPLING.
+   * the factor set with ::JXL_ENC_FRAME_SETTING_RESAMPLING.
    * Use 0 to disable, 1 to enable. Default value is 0.
    */
   JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED = 4,
@@ -171,8 +171,8 @@ typedef enum {
   JXL_ENC_FRAME_SETTING_PHOTON_NOISE = 5,
 
   /** Enables adaptive noise generation. This setting is not recommended for
-   * use, please use JXL_ENC_FRAME_SETTING_PHOTON_NOISE instead. Use -1 for the
-   * default (encoder chooses), 0 to disable, 1 to enable.
+   * use, please use ::JXL_ENC_FRAME_SETTING_PHOTON_NOISE instead. Use -1 for
+   * the default (encoder chooses), 0 to disable, 1 to enable.
    */
   JXL_ENC_FRAME_SETTING_NOISE = 6,
 
@@ -320,27 +320,28 @@ typedef enum {
    * 1 = index this frame within the Frame Index Box.
    * If any frames are indexed, the first frame needs to
    * be indexed, too. If the first frame is not indexed, and
-   * a later frame is attempted to be indexed, JXL_ENC_ERROR will occur.
+   * a later frame is attempted to be indexed, ::JXL_ENC_ERROR will occur.
    * If non-keyframes, i.e., frames with cropping, blending or patches are
-   * attempted to be indexed, JXL_ENC_ERROR will occur.
+   * attempted to be indexed, ::JXL_ENC_ERROR will occur.
    */
   JXL_ENC_FRAME_INDEX_BOX = 31,
 
-  /** Sets brotli encode effort for use in JPEG recompression and compressed
-   * metadata boxes (brob). Can be -1 (default) or 0 (fastest) to 11 (slowest).
-   * Default is based on the general encode effort in case of JPEG
+  /** Sets brotli encode effort for use in JPEG recompression and
+   * compressed metadata boxes (brob). Can be -1 (default) or 0 (fastest) to 11
+   * (slowest). Default is based on the general encode effort in case of JPEG
    * recompression, and 4 for brob boxes.
    */
   JXL_ENC_FRAME_SETTING_BROTLI_EFFORT = 32,
 
   /** Enables or disables brotli compression of metadata boxes derived from
-   * a JPEG frame when using JxlEncoderAddJPEGFrame. This has no effect on boxes
-   * added using JxlEncoderAddBox.
-   * -1 = default, 0 = disable compression, 1 = enable compression.
+   * a JPEG frame when using @ref JxlEncoderAddJPEGFrame. This has no effect on
+   * boxes added using @ref JxlEncoderAddBox. -1 = default, 0 = disable
+   * compression, 1 = enable compression.
    */
   JXL_ENC_FRAME_SETTING_JPEG_COMPRESS_BOXES = 33,
 
   /** Control what kind of buffering is used, when using chunked image frames.
+   * -1 = default (let the encoder decide)
    * 0 = buffers everything, basically the same as non-streamed code path
    (mainly for testing)
    * 1 = buffers everything for images that are smaller than 2048 x 2048, and
@@ -351,30 +352,30 @@ typedef enum {
    *
    * When using streaming input and output the encoder minimizes memory usage at
    * the cost of compression density. Also note that images produced with
-   * streaming mode might can not be decoded progressively.
+   * streaming mode might not be progressively decodeable.
    */
   JXL_ENC_FRAME_SETTING_BUFFERING = 34,
 
   /** Keep or discard Exif metadata boxes derived from a JPEG frame when using
-   * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
-   * JxlEncoderAddBox. When JxlEncoderStoreJPEGMetadata is set to 1, this option
-   * cannot be set to 0. Even when Exif metadata is discarded, the orientation
-   * will still be applied. 0 = discard Exif metadata, 1 = keep Exif metadata
-   * (default).
+   * @ref JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+   * @ref JxlEncoderAddBox. When @ref JxlEncoderStoreJPEGMetadata is set to 1,
+   * this option cannot be set to 0. Even when Exif metadata is discarded, the
+   * orientation will still be applied. 0 = discard Exif metadata, 1 = keep Exif
+   * metadata (default).
    */
   JXL_ENC_FRAME_SETTING_JPEG_KEEP_EXIF = 35,
 
   /** Keep or discard XMP metadata boxes derived from a JPEG frame when using
-   * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
-   * JxlEncoderAddBox. When JxlEncoderStoreJPEGMetadata is set to 1, this option
-   * cannot be set to 0. 0 = discard XMP metadata, 1 = keep XMP metadata
-   * (default).
+   * @ref JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+   * @ref JxlEncoderAddBox. When @ref JxlEncoderStoreJPEGMetadata is set to 1,
+   * this option cannot be set to 0. 0 = discard XMP metadata, 1 = keep XMP
+   * metadata (default).
    */
   JXL_ENC_FRAME_SETTING_JPEG_KEEP_XMP = 36,
 
   /** Keep or discard JUMBF metadata boxes derived from a JPEG frame when using
-   * JxlEncoderAddJPEGFrame. This has no effect on boxes added using
-   * JxlEncoderAddBox. 0 = discard JUMBF metadata, 1 = keep JUMBF metadata
+   * @ref JxlEncoderAddJPEGFrame. This has no effect on boxes added using
+   * @ref JxlEncoderAddBox. 0 = discard JUMBF metadata, 1 = keep JUMBF metadata
    * (default).
    */
   JXL_ENC_FRAME_SETTING_JPEG_KEEP_JUMBF = 37,
@@ -395,7 +396,7 @@ typedef enum {
 } JxlEncoderFrameSettingId;
 
 /**
- * Creates an instance of JxlEncoder and initializes it.
+ * Creates an instance of @ref JxlEncoder and initializes it.
  *
  * @p memory_manager will be used for all the library dynamic allocations made
  * from this instance. The parameter may be NULL, in which case the default
@@ -404,21 +405,21 @@ typedef enum {
  * @param memory_manager custom allocator function. It may be NULL. The memory
  *        manager will be copied internally.
  * @return @c NULL if the instance can not be allocated or initialized
- * @return pointer to initialized JxlEncoder otherwise
+ * @return pointer to initialized @ref JxlEncoder otherwise
  */
 JXL_EXPORT JxlEncoder* JxlEncoderCreate(const JxlMemoryManager* memory_manager);
 
 /**
- * Re-initializes a JxlEncoder instance, so it can be re-used for encoding
+ * Re-initializes a @ref JxlEncoder instance, so it can be re-used for encoding
  * another image. All state and settings are reset as if the object was
- * newly created with JxlEncoderCreate, but the memory manager is kept.
+ * newly created with @ref JxlEncoderCreate, but the memory manager is kept.
  *
  * @param enc instance to be re-initialized.
  */
 JXL_EXPORT void JxlEncoderReset(JxlEncoder* enc);
 
 /**
- * Deinitializes and frees JxlEncoder instance.
+ * Deinitializes and frees a @ref JxlEncoder instance.
  *
  * @param enc instance to be cleaned up and deallocated.
  */
@@ -430,8 +431,8 @@ JXL_EXPORT void JxlEncoderDestroy(JxlEncoder* enc);
  * left unset, the default CMS implementation will be used.
  *
  * @param enc encoder object.
- * @param cms structure representing a CMS implementation. See JxlCmsInterface
- * for more details.
+ * @param cms structure representing a CMS implementation. See @ref
+ * JxlCmsInterface for more details.
  */
 JXL_EXPORT void JxlEncoderSetCms(JxlEncoder* enc, JxlCmsInterface cms);
 
@@ -444,7 +445,7 @@ JXL_EXPORT void JxlEncoderSetCms(JxlEncoder* enc, JxlCmsInterface cms);
  *        be NULL to use the default, single-threaded, runner. A multithreaded
  *        runner should be set to reach fast performance.
  * @param parallel_runner_opaque opaque pointer for parallel_runner.
- * @return JXL_ENC_SUCCESS if the runner was set, JXL_ENC_ERROR
+ * @return ::JXL_ENC_SUCCESS if the runner was set, ::JXL_ENC_ERROR
  * otherwise (the previous runner remains set).
  */
 JXL_EXPORT JxlEncoderStatus
@@ -452,16 +453,16 @@ JxlEncoderSetParallelRunner(JxlEncoder* enc, JxlParallelRunner parallel_runner,
                             void* parallel_runner_opaque);
 
 /**
- * Get the (last) error code in case JXL_ENC_ERROR was returned.
+ * Get the (last) error code in case ::JXL_ENC_ERROR was returned.
  *
  * @param enc encoder object.
- * @return the JxlEncoderError that caused the (last) JXL_ENC_ERROR to be
- * returned.
+ * @return the @ref JxlEncoderError that caused the (last) ::JXL_ENC_ERROR to
+ * be returned.
  */
 JXL_EXPORT JxlEncoderError JxlEncoderGetError(JxlEncoder* enc);
 
 /**
- * Encodes JPEG XL file using the available bytes. @p *avail_out indicates how
+ * Encodes a JPEG XL file using the available bytes. @p *avail_out indicates how
  * many output bytes are available, and @p *next_out points to the input bytes.
  * *avail_out will be decremented by the amount of bytes that have been
  * processed by the encoder and *next_out will be incremented by the same
@@ -469,12 +470,12 @@ JXL_EXPORT JxlEncoderError JxlEncoderGetError(JxlEncoder* enc);
  * bytes.
  *
  * The returned status indicates whether the encoder needs more output bytes.
- * When the return value is not JXL_ENC_ERROR or JXL_ENC_SUCCESS, the encoding
- * requires more JxlEncoderProcessOutput calls to continue.
+ * When the return value is not ::JXL_ENC_ERROR or ::JXL_ENC_SUCCESS, the
+ * encoding requires more @ref JxlEncoderProcessOutput calls to continue.
  *
  * The caller must guarantee that *avail_out >= 32 when calling
- * JxlEncoderProcessOutput; otherwise, JXL_ENC_NEED_MORE_OUTPUT will be
- * returned. It is guaranteed that, if *avail_out >= 32, at least one byte of
+ * @ref JxlEncoderProcessOutput; otherwise, ::JXL_ENC_NEED_MORE_OUTPUT will
+ * be returned. It is guaranteed that, if *avail_out >= 32, at least one byte of
  * output will be written.
  *
  * This encodes the frames and/or boxes added so far. If the last frame or last
@@ -486,9 +487,9 @@ JXL_EXPORT JxlEncoderError JxlEncoderGetError(JxlEncoder* enc);
  * @param enc encoder object.
  * @param next_out pointer to next bytes to write to.
  * @param avail_out amount of bytes available starting from *next_out.
- * @return JXL_ENC_SUCCESS when encoding finished and all events handled.
- * @return JXL_ENC_ERROR when encoding failed, e.g. invalid input.
- * @return JXL_ENC_NEED_MORE_OUTPUT more output buffer is necessary.
+ * @return ::JXL_ENC_SUCCESS when encoding finished and all events handled.
+ * @return ::JXL_ENC_ERROR when encoding failed, e.g. invalid input.
+ * @return ::JXL_ENC_NEED_MORE_OUTPUT more output buffer is necessary.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput(JxlEncoder* enc,
                                                     uint8_t** next_out,
@@ -509,13 +510,14 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput(JxlEncoder* enc,
  * time duration of 0, making them form a composite still. See @ref
  * JxlFrameHeader for more information.
  *
- * This information is stored in the JxlEncoderFrameSettings and so is used for
- * any frame encoded with these JxlEncoderFrameSettings. It is ok to change
- * between @ref JxlEncoderAddImageFrame calls, each added image frame will have
- * the frame header that was set in the options at the time of calling
- * JxlEncoderAddImageFrame.
+ * This information is stored in the @ref JxlEncoderFrameSettings and so is used
+ * for any frame encoded with these @ref JxlEncoderFrameSettings. It is ok to
+ * change between @ref JxlEncoderAddImageFrame calls, each added image frame
+ * will have the frame header that was set in the options at the time of calling
+ * @ref JxlEncoderAddImageFrame.
  *
- * The is_last and name_length fields of the JxlFrameHeader are ignored, use
+ * The is_last and name_length fields of the @ref JxlFrameHeader are ignored,
+ * use
  * @ref JxlEncoderCloseFrames to indicate last frame, and @ref
  * JxlEncoderSetFrameName to indicate the name and its length instead.
  * Calling this function will clear any name that was previously set with @ref
@@ -525,7 +527,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderProcessOutput(JxlEncoder* enc,
  * includes reference to the encoder object.
  * @param frame_header frame header data to set. Object owned by the caller and
  * does not need to be kept in memory, its information is copied internally.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus
 JxlEncoderSetFrameHeader(JxlEncoderFrameSettings* frame_settings,
@@ -540,7 +542,7 @@ JxlEncoderSetFrameHeader(JxlEncoderFrameSettings* frame_settings,
  * includes reference to the encoder object.
  * @param index index of the extra channel to use.
  * @param blend_info blend info to set for the extra channel
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBlendInfo(
     JxlEncoderFrameSettings* frame_settings, size_t index,
@@ -550,8 +552,9 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBlendInfo(
  * Sets the name of the animation frame. This function is optional, frames are
  * not required to have a name. This setting is a part of the frame header, and
  * the same principles as for @ref JxlEncoderSetFrameHeader apply. The
- * name_length field of JxlFrameHeader is ignored by the encoder, this function
- * determines the name length instead as the length in bytes of the C string.
+ * name_length field of @ref JxlFrameHeader is ignored by the encoder, this
+ * function determines the name length instead as the length in bytes of the C
+ * string.
  *
  * The maximum possible name length is 1071 bytes (excluding terminating null
  * character).
@@ -563,7 +566,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBlendInfo(
  * includes reference to the encoder object.
  * @param frame_name name of the next frame to be encoded, as a UTF-8 encoded C
  * string (zero terminated). Owned by the caller, and copied internally.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameName(
     JxlEncoderFrameSettings* frame_settings, const char* frame_name);
@@ -571,15 +574,17 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameName(
 /**
  * Sets the bit depth of the input buffer.
  *
- * For float pixel formats, only the default JXL_BIT_DEPTH_FROM_PIXEL_FORMAT
+ * For float pixel formats, only the default @ref
+ JXL_BIT_DEPTH_FROM_PIXEL_FORMAT
  * setting is allowed, while for unsigned pixel formats,
- * JXL_BIT_DEPTH_FROM_CODESTREAM setting is also allowed. See the comment on
+ * ::JXL_BIT_DEPTH_FROM_CODESTREAM setting is also allowed. See the comment
+ on
  * @ref JxlEncoderAddImageFrame for the effects of the bit depth setting.
 
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
  * @param bit_depth the bit depth setting of the pixel input
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameBitDepth(
     JxlEncoderFrameSettings* frame_settings, const JxlBitDepth* bit_depth);
@@ -587,13 +592,13 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameBitDepth(
 /**
  * Sets the buffer to read JPEG encoded bytes from for the next frame to encode.
  *
- * If JxlEncoderSetBasicInfo has not yet been called, calling
- * JxlEncoderAddJPEGFrame will implicitly call it with the parameters of the
- * added JPEG frame.
+ * If @ref JxlEncoderSetBasicInfo has not yet been called, calling
+ * @ref JxlEncoderAddJPEGFrame will implicitly call it with the parameters of
+ * the added JPEG frame.
  *
- * If JxlEncoderSetColorEncoding or JxlEncoderSetICCProfile has not yet been
- * called, calling JxlEncoderAddJPEGFrame will implicitly call it with the
- * parameters of the added JPEG frame.
+ * If @ref JxlEncoderSetColorEncoding or @ref JxlEncoderSetICCProfile has not
+ * yet been called, calling @ref JxlEncoderAddJPEGFrame will implicitly call it
+ * with the parameters of the added JPEG frame.
  *
  * If the encoder is set to store JPEG reconstruction metadata using @ref
  * JxlEncoderStoreJPEGMetadata and a single JPEG frame is added, it will be
@@ -603,12 +608,16 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameBitDepth(
  * JxlEncoderCloseFrames must be called before the next
  * @ref JxlEncoderProcessOutput call.
  *
+ * Note, this can only be used to add JPEG frames for lossless compression. To
+ * encode with lossy compression, the JPEG must be decoded manually and a pixel
+ * buffer added using JxlEncoderAddImageFrame.
+ *
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
  * @param buffer bytes to read JPEG from. Owned by the caller and its contents
  * are copied internally.
  * @param size size of buffer in bytes.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus
 JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
@@ -616,33 +625,36 @@ JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
 
 /**
  * Sets the buffer to read pixels from for the next image to encode. Must call
- * JxlEncoderSetBasicInfo before JxlEncoderAddImageFrame.
+ * @ref JxlEncoderSetBasicInfo before @ref JxlEncoderAddImageFrame.
  *
  * Currently only some data types for pixel formats are supported:
- * - JXL_TYPE_UINT8, with range 0..255
- * - JXL_TYPE_UINT16, with range 0..65535
- * - JXL_TYPE_FLOAT16, with nominal range 0..1
- * - JXL_TYPE_FLOAT, with nominal range 0..1
+ * - ::JXL_TYPE_UINT8, with range 0..255
+ * - ::JXL_TYPE_UINT16, with range 0..65535
+ * - ::JXL_TYPE_FLOAT16, with nominal range 0..1
+ * - ::JXL_TYPE_FLOAT, with nominal range 0..1
  *
  * Note: the sample data type in pixel_format is allowed to be different from
- * what is described in the JxlBasicInfo. The type in pixel_format, together
- * with an optional @ref JxlBitDepth parameter set by @ref
+ * what is described in the @ref JxlBasicInfo. The type in pixel_format,
+ * together with an optional @ref JxlBitDepth parameter set by @ref
  * JxlEncoderSetFrameBitDepth describes the format of the uncompressed pixel
- * buffer. The bits_per_sample and exponent_bits_per_sample in the JxlBasicInfo
- * describes what will actually be encoded in the JPEG XL codestream.
- * For example, to encode a 12-bit image, you would set bits_per_sample to 12,
- * while the input frame buffer can be in the following formats:
- *  - if pixel format is in JXL_TYPE_UINT16 with default bit depth setting
- *    (i.e. JXL_BIT_DEPTH_FROM_PIXEL_FORMAT), input sample values are rescaled
- *    to 16-bit, i.e. multiplied by 65535/4095;
- *  - if pixel format is in JXL_TYPE_UINT16 with JXL_BIT_DEPTH_FROM_CODESTREAM
- *    bit depth setting, input sample values are provided unscaled;
- *  - if pixel format is in JXL_TYPE_FLOAT, input sample values are rescaled
- *    to 0..1, i.e.  multiplied by 1.f/4095.f.
- * While it is allowed, it is obviously not recommended to use a pixel_format
- * with lower precision than what is specified in the JxlBasicInfo.
- *
- * We support interleaved channels as described by the JxlPixelFormat:
+ * buffer. The bits_per_sample and exponent_bits_per_sample in the @ref
+ * JxlBasicInfo describes what will actually be encoded in the JPEG XL
+ * codestream. For example, to encode a 12-bit image, you would set
+ * bits_per_sample to 12, while the input frame buffer can be in the following
+ * formats:
+ *  - if pixel format is in ::JXL_TYPE_UINT16 with default bit depth setting
+ *    (i.e. ::JXL_BIT_DEPTH_FROM_PIXEL_FORMAT), input sample values are
+ * rescaled to 16-bit, i.e. multiplied by 65535/4095;
+ *  - if pixel format is in ::JXL_TYPE_UINT16 with @ref
+ * JXL_BIT_DEPTH_FROM_CODESTREAM bit depth setting, input sample values are
+ * provided unscaled;
+ *  - if pixel format is in ::JXL_TYPE_FLOAT, input sample values are
+ * rescaled to 0..1, i.e.  multiplied by 1.f/4095.f. While it is allowed, it is
+ * obviously not recommended to use a pixel_format with lower precision than
+ * what is specified in the @ref JxlBasicInfo.
+ *
+ * We support interleaved channels as described by the @ref JxlPixelFormat
+ * "JxlPixelFormat":
  * - single-channel data, e.g. grayscale
  * - single-channel + alpha
  * - trichromatic, e.g. RGB
@@ -654,10 +666,11 @@ JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
  * set to all-opaque (an alpha value of 1.0 everywhere).
  *
  * The pixels are assumed to be encoded in the original profile that is set with
- * JxlEncoderSetColorEncoding or JxlEncoderSetICCProfile. If none of these
- * functions were used, the pixels are assumed to be nonlinear sRGB for integer
- * data types (JXL_TYPE_UINT8, JXL_TYPE_UINT16), and linear sRGB for floating
- * point data types (JXL_TYPE_FLOAT16, JXL_TYPE_FLOAT).
+ * @ref JxlEncoderSetColorEncoding or @ref JxlEncoderSetICCProfile. If none of
+ * these functions were used, the pixels are assumed to be nonlinear sRGB for
+ * integer data types (::JXL_TYPE_UINT8, ::JXL_TYPE_UINT16), and linear
+ * sRGB for floating point data types (::JXL_TYPE_FLOAT16, @ref
+ * JXL_TYPE_FLOAT).
  *
  * Sample values in floating-point pixel formats are allowed to be outside the
  * nominal range, e.g. to represent out-of-sRGB-gamut colors in the
@@ -676,14 +689,14 @@ JxlEncoderAddJPEGFrame(const JxlEncoderFrameSettings* frame_settings,
  * and its contents are copied internally.
  * @param size size of buffer in bytes. This size should match what is implied
  * by the frame dimensions and the pixel format.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderAddImageFrame(
     const JxlEncoderFrameSettings* frame_settings,
     const JxlPixelFormat* pixel_format, const void* buffer, size_t size);
 
 /**
- * The JxlEncoderOutputProcessor structure provides an interface for the
+ * The @ref JxlEncoderOutputProcessor structure provides an interface for the
  * encoder's output processing. Users of the library, who want to do streaming
  * encoding, should implement the required callbacks for buffering, writing,
  * seeking (if supported), and setting a finalized position during the encoding
@@ -785,7 +798,7 @@ struct JxlEncoderOutputProcessor {
  * @param enc encoder object.
  * @param output_processor the struct containing the callbacks for managing
  * output.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error.
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetOutputProcessor(
     JxlEncoder* enc, struct JxlEncoderOutputProcessor output_processor);
@@ -801,7 +814,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetOutputProcessor(
  * This should not be used when using @ref JxlEncoderProcessOutput.
  *
  * @param enc encoder object.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error.
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderFlushInput(JxlEncoder* enc);
 
@@ -923,9 +936,9 @@ struct JxlChunkedFrameInputSource {
  * chunked or streaming manner, which can be especially useful when dealing with
  * large images that may not fit entirely in memory or when trying to optimize
  * memory usage. The input data is provided through callbacks defined in the
- * `JxlChunkedFrameInputSource` struct. Once the frame data has been completely
- * retrieved, this function will flush the input and close it if it is the last
- * frame.
+ * @ref JxlChunkedFrameInputSource struct. Once the frame data has been
+ * completely retrieved, this function will flush the input and close it if it
+ * is the last frame.
  *
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
@@ -943,7 +956,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderAddChunkedFrame(
 /**
  * Sets the buffer to read pixels from for an extra channel at a given index.
  * The index must be smaller than the num_extra_channels in the associated
- * JxlBasicInfo. Must call @ref JxlEncoderSetExtraChannelInfo before
+ * @ref JxlBasicInfo. Must call @ref JxlEncoderSetExtraChannelInfo before @ref
  * JxlEncoderSetExtraChannelBuffer.
  *
  * TODO(firsching): mention what data types in pixel formats are supported.
@@ -961,15 +974,15 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderAddChunkedFrame(
  * @param size size of buffer in bytes. This size should match what is implied
  * by the frame dimensions and the pixel format.
  * @param index index of the extra channel to use.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBuffer(
     const JxlEncoderFrameSettings* frame_settings,
     const JxlPixelFormat* pixel_format, const void* buffer, size_t size,
     uint32_t index);
 
-/** Adds a metadata box to the file format. JxlEncoderProcessOutput must be used
- * to effectively write the box to the output. @ref JxlEncoderUseBoxes must
+/** Adds a metadata box to the file format. @ref JxlEncoderProcessOutput must be
+ * used to effectively write the box to the output. @ref JxlEncoderUseBoxes must
  * be enabled before using this function.
  *
  * Boxes allow inserting application-specific data and metadata (Exif, XML/XMP,
@@ -996,10 +1009,10 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBuffer(
  * the encoder encodes the size header itself. Most boxes are written
  * automatically by the encoder as needed ("JXL ", "ftyp", "jxll", "jxlc",
  * "jxlp", "jxli", "jbrd"), and this function only needs to be called to add
- * optional metadata when encoding from pixels (using JxlEncoderAddImageFrame).
- * When recompressing JPEG files (using JxlEncoderAddJPEGFrame), if the input
- * JPEG contains EXIF, XMP or JUMBF metadata, the corresponding boxes are
- * already added automatically.
+ * optional metadata when encoding from pixels (using @ref
+ * JxlEncoderAddImageFrame). When recompressing JPEG files (using @ref
+ * JxlEncoderAddJPEGFrame), if the input JPEG contains EXIF, XMP or JUMBF
+ * metadata, the corresponding boxes are already added automatically.
  *
  * Box types are given by 4 characters. The following boxes can be added with
  * this function:
@@ -1032,9 +1045,9 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelBuffer(
  * @param size size of the box contents.
  * @param compress_box Whether to compress this box as a "brob" box. Requires
  * Brotli support.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error, such as when
- * using this function without JxlEncoderUseContainer, or adding a box type
- * that would result in an invalid file format.
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error, such as
+ * when using this function without @ref JxlEncoderUseContainer, or adding a box
+ * type that would result in an invalid file format.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderAddBox(JxlEncoder* enc,
                                              const JxlBoxType type,
@@ -1061,9 +1074,9 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderUseBoxes(JxlEncoder* enc);
  * the stream will be finished. It is not necessary to use this function if
  * @ref JxlEncoderUseBoxes is not used. Further frames may still be added.
  *
- * Must be called between JxlEncoderAddBox of the last box
- * and the next call to JxlEncoderProcessOutput, or @ref JxlEncoderProcessOutput
- * won't output the last box correctly.
+ * Must be called between @ref JxlEncoderAddBox of the last box
+ * and the next call to @ref JxlEncoderProcessOutput, or @ref
+ * JxlEncoderProcessOutput won't output the last box correctly.
  *
  * NOTE: if you don't need to close frames and boxes at separate times, you can
  * use @ref JxlEncoderCloseInput instead to close both at once.
@@ -1087,10 +1100,10 @@ JXL_EXPORT void JxlEncoderCloseBoxes(JxlEncoder* enc);
 JXL_EXPORT void JxlEncoderCloseFrames(JxlEncoder* enc);
 
 /**
- * Closes any input to the encoder, equivalent to calling JxlEncoderCloseFrames
- * as well as calling JxlEncoderCloseBoxes if needed. No further input of any
- * kind may be given to the encoder, but further @ref JxlEncoderProcessOutput
- * calls should be done to create the final output.
+ * Closes any input to the encoder, equivalent to calling @ref
+ * JxlEncoderCloseFrames as well as calling @ref JxlEncoderCloseBoxes if needed.
+ * No further input of any kind may be given to the encoder, but further @ref
+ * JxlEncoderProcessOutput calls should be done to create the final output.
  *
  * The requirements of both @ref JxlEncoderCloseFrames and @ref
  * JxlEncoderCloseBoxes apply to this function. Either this function or the
@@ -1104,39 +1117,39 @@ JXL_EXPORT void JxlEncoderCloseInput(JxlEncoder* enc);
 
 /**
  * Sets the original color encoding of the image encoded by this encoder. This
- * is an alternative to JxlEncoderSetICCProfile and only one of these two must
- * be used. This one sets the color encoding as a @ref JxlColorEncoding, while
- * the other sets it as ICC binary data.
- * Must be called after JxlEncoderSetBasicInfo.
+ * is an alternative to @ref JxlEncoderSetICCProfile and only one of these two
+ * must be used. This one sets the color encoding as a @ref JxlColorEncoding,
+ * while the other sets it as ICC binary data. Must be called after @ref
+ * JxlEncoderSetBasicInfo.
  *
  * @param enc encoder object.
  * @param color color encoding. Object owned by the caller and its contents are
  * copied internally.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or
- * JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise
  */
 JXL_EXPORT JxlEncoderStatus
 JxlEncoderSetColorEncoding(JxlEncoder* enc, const JxlColorEncoding* color);
 
 /**
  * Sets the original color encoding of the image encoded by this encoder as an
- * ICC color profile. This is an alternative to JxlEncoderSetColorEncoding and
- * only one of these two must be used. This one sets the color encoding as ICC
- * binary data, while the other defines it as a @ref JxlColorEncoding.
- * Must be called after JxlEncoderSetBasicInfo.
+ * ICC color profile. This is an alternative to @ref JxlEncoderSetColorEncoding
+ * and only one of these two must be used. This one sets the color encoding as
+ * ICC binary data, while the other defines it as a @ref JxlColorEncoding. Must
+ * be called after @ref JxlEncoderSetBasicInfo.
  *
  * @param enc encoder object.
  * @param icc_profile bytes of the original ICC profile
  * @param size size of the icc_profile buffer in bytes
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR or
- * JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetICCProfile(JxlEncoder* enc,
                                                     const uint8_t* icc_profile,
                                                     size_t size);
 
 /**
- * Initializes a JxlBasicInfo struct to default values.
+ * Initializes a @ref JxlBasicInfo struct to default values.
  * For forwards-compatibility, this function has to be called before values
  * are assigned to the struct fields.
  * The default values correspond to an 8-bit RGB image, no alpha or any
@@ -1147,7 +1160,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetICCProfile(JxlEncoder* enc,
 JXL_EXPORT void JxlEncoderInitBasicInfo(JxlBasicInfo* info);
 
 /**
- * Initializes a JxlFrameHeader struct to default values.
+ * Initializes a @ref JxlFrameHeader struct to default values.
  * For forwards-compatibility, this function has to be called before values
  * are assigned to the struct fields.
  * The default values correspond to a frame with no animation duration and the
@@ -1159,7 +1172,7 @@ JXL_EXPORT void JxlEncoderInitBasicInfo(JxlBasicInfo* info);
 JXL_EXPORT void JxlEncoderInitFrameHeader(JxlFrameHeader* frame_header);
 
 /**
- * Initializes a JxlBlendInfo struct to default values.
+ * Initializes a @ref JxlBlendInfo struct to default values.
  * For forwards-compatibility, this function has to be called before values
  * are assigned to the struct fields.
  *
@@ -1170,26 +1183,26 @@ JXL_EXPORT void JxlEncoderInitBlendInfo(JxlBlendInfo* blend_info);
 /**
  * Sets the global metadata of the image encoded by this encoder.
  *
- * If the JxlBasicInfo contains information of extra channels beyond an alpha
- * channel, then @ref JxlEncoderSetExtraChannelInfo must be called between
- * JxlEncoderSetBasicInfo and @ref JxlEncoderAddImageFrame. In order to indicate
- * extra channels, the value of `info.num_extra_channels` should be set to the
- * number of extra channels, also counting the alpha channel if present.
+ * If the @ref JxlBasicInfo contains information of extra channels beyond an
+ * alpha channel, then @ref JxlEncoderSetExtraChannelInfo must be called between
+ * @ref JxlEncoderSetBasicInfo and @ref JxlEncoderAddImageFrame. In order to
+ * indicate extra channels, the value of `info.num_extra_channels` should be set
+ * to the number of extra channels, also counting the alpha channel if present.
  *
  * @param enc encoder object.
  * @param info global image metadata. Object owned by the caller and its
  * contents are copied internally.
- * @return JXL_ENC_SUCCESS if the operation was successful,
- * JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful,
+ * ::JXL_ENC_ERROR otherwise
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetBasicInfo(JxlEncoder* enc,
                                                    const JxlBasicInfo* info);
 
 /**
  * Sets the upsampling method the decoder will use in case there are frames
- * with JXL_ENC_FRAME_SETTING_RESAMPLING set. This is useful in combination
- * with the JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED option, to control the
- * type of upsampling that will be used.
+ * with ::JXL_ENC_FRAME_SETTING_RESAMPLING set. This is useful in combination
+ * with the ::JXL_ENC_FRAME_SETTING_ALREADY_DOWNSAMPLED option, to control
+ * the type of upsampling that will be used.
  *
  * @param enc encoder object.
  * @param factor upsampling factor to configure (1, 2, 4 or 8; for 1 this
@@ -1198,15 +1211,15 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetBasicInfo(JxlEncoder* enc,
  * -1: default (good for photographic images, no signaling overhead)
  * 0: nearest neighbor (good for pixel art)
  * 1: 'pixel dots' (same as NN for 2x, diamond-shaped 'pixel dots' for 4x/8x)
- * @return JXL_ENC_SUCCESS if the operation was successful,
- * JXL_ENC_ERROR or JXL_ENC_NOT_SUPPORTED otherwise
+ * @return ::JXL_ENC_SUCCESS if the operation was successful,
+ * ::JXL_ENC_ERROR otherwise
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetUpsamplingMode(JxlEncoder* enc,
                                                         int64_t factor,
                                                         int64_t mode);
 
 /**
- * Initializes a JxlExtraChannelInfo struct to default values.
+ * Initializes a @ref JxlExtraChannelInfo struct to default values.
  * For forwards-compatibility, this function has to be called before values
  * are assigned to the struct fields.
  * The default values correspond to an 8-bit channel of the provided type.
@@ -1220,23 +1233,24 @@ JXL_EXPORT void JxlEncoderInitExtraChannelInfo(JxlExtraChannelType type,
 
 /**
  * Sets information for the extra channel at the given index. The index
- * must be smaller than num_extra_channels in the associated JxlBasicInfo.
+ * must be smaller than num_extra_channels in the associated @ref JxlBasicInfo.
  *
  * @param enc encoder object
  * @param index index of the extra channel to set.
  * @param info global extra channel metadata. Object owned by the caller and its
  * contents are copied internally.
- * @return JXL_ENC_SUCCESS on success, JXL_ENC_ERROR on error
+ * @return ::JXL_ENC_SUCCESS on success, ::JXL_ENC_ERROR on error
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelInfo(
     JxlEncoder* enc, size_t index, const JxlExtraChannelInfo* info);
 
 /**
  * Sets the name for the extra channel at the given index in UTF-8. The index
- * must be smaller than the num_extra_channels in the associated JxlBasicInfo.
+ * must be smaller than the num_extra_channels in the associated @ref
+ * JxlBasicInfo.
  *
  * TODO(lode): remove size parameter for consistency with
- * JxlEncoderSetFrameName
+ * @ref JxlEncoderSetFrameName
  *
  * @param enc encoder object
  * @param index index of the extra channel to set.
@@ -1252,17 +1266,18 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelName(JxlEncoder* enc,
 
 /**
  * Sets a frame-specific option of integer type to the encoder options.
- * The JxlEncoderFrameSettingId argument determines which option is set.
+ * The @ref JxlEncoderFrameSettingId argument determines which option is set.
  *
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
  * @param option ID of the option to set.
  * @param value Integer value to set for this option.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR in
- * case of an error, such as invalid or unknown option id, or invalid integer
- * value for the given option. If an error is returned, the state of the
- * JxlEncoderFrameSettings object is still valid and is the same as before this
- * function was called.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR in case of an error, such as invalid or unknown option id, or
+ * invalid integer value for the given option. If an error is returned, the
+ * state of the
+ * @ref JxlEncoderFrameSettings object is still valid and is the same as before
+ * this function was called.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetOption(
     JxlEncoderFrameSettings* frame_settings, JxlEncoderFrameSettingId option,
@@ -1270,17 +1285,18 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetOption(
 
 /**
  * Sets a frame-specific option of float type to the encoder options.
- * The JxlEncoderFrameSettingId argument determines which option is set.
+ * The @ref JxlEncoderFrameSettingId argument determines which option is set.
  *
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
  * @param option ID of the option to set.
  * @param value Float value to set for this option.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR in
- * case of an error, such as invalid or unknown option id, or invalid integer
- * value for the given option. If an error is returned, the state of the
- * JxlEncoderFrameSettings object is still valid and is the same as before this
- * function was called.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR in case of an error, such as invalid or unknown option id, or
+ * invalid integer value for the given option. If an error is returned, the
+ * state of the
+ * @ref JxlEncoderFrameSettings object is still valid and is the same as before
+ * this function was called.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetFloatOption(
     JxlEncoderFrameSettings* frame_settings, JxlEncoderFrameSettingId option,
@@ -1292,7 +1308,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderFrameSettingsSetFloatOption(
  * When using @ref JxlEncoderUseBoxes, @ref JxlEncoderStoreJPEGMetadata or @ref
  * JxlEncoderSetCodestreamLevel with level 10, the encoder will automatically
  * also use the container format, it is not necessary to use
- * JxlEncoderUseContainer for those use cases.
+ * @ref JxlEncoderUseContainer for those use cases.
  *
  * By default this setting is disabled.
  *
@@ -1318,8 +1334,8 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderUseContainer(JxlEncoder* enc,
  *
  * @param enc encoder object.
  * @param store_jpeg_metadata true if the encoder should store JPEG metadata.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
  */
 JXL_EXPORT JxlEncoderStatus
 JxlEncoderStoreJPEGMetadata(JxlEncoder* enc, JXL_BOOL store_jpeg_metadata);
@@ -1334,8 +1350,8 @@ JxlEncoderStoreJPEGMetadata(JxlEncoder* enc, JXL_BOOL store_jpeg_metadata);
  * 268435456 pixels total with a maximum width or height of 262144 pixels,
  * maximum 16-bit color channel depth, maximum 120 frames per second for
  * animation, maximum ICC color profile size of 4 MiB, it allows all color
- * models and extra channel types except CMYK and the JXL_CHANNEL_BLACK extra
- * channel, and a maximum of 4 extra channels in addition to the 3 color
+ * models and extra channel types except CMYK and the JXL_CHANNEL_BLACK
+ * extra channel, and a maximum of 4 extra channels in addition to the 3 color
  * channels. It also sets boundaries to certain internally used coding tools.
  *
  * Level 10: this level removes or increases the bounds of most of the level
@@ -1355,8 +1371,8 @@ JxlEncoderStoreJPEGMetadata(JxlEncoder* enc, JXL_BOOL store_jpeg_metadata);
  *
  * @param enc encoder object.
  * @param level the level value to set, must be -1, 5, or 10.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetCodestreamLevel(JxlEncoder* enc,
                                                          int level);
@@ -1370,9 +1386,10 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetCodestreamLevel(JxlEncoder* enc,
  * the JPEG XL file.
  *
  * If this returns 5, nothing needs to be done and the codestream can be
- * compatible with any decoder. If this returns 10, JxlEncoderSetCodestreamLevel
- * has to be used to set the codestream level to 10, or the encoder can be
- * configured differently to allow using the more compatible level 5.
+ * compatible with any decoder. If this returns 10, @ref
+ * JxlEncoderSetCodestreamLevel has to be used to set the codestream level to
+ * 10, or the encoder can be configured differently to allow using the more
+ * compatible level 5.
  *
  * @param enc encoder object.
  * @return -1 if no level can support the configuration (e.g. image dimensions
@@ -1391,14 +1408,14 @@ JXL_EXPORT int JxlEncoderGetRequiredCodestreamLevel(const JxlEncoder* enc);
  *
  * When disabled, those options are not overridden, but since those options
  * could still have been manually set to a combination that operates losslessly,
- * using this function with lossless set to JXL_DEC_FALSE does not guarantee
- * lossy encoding, though the default set of options is lossy.
+ * using this function with lossless set to ::JXL_FALSE does not
+ * guarantee lossy encoding, though the default set of options is lossy.
  *
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
  * @param lossless whether to override options for lossless mode
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameLossless(
     JxlEncoderFrameSettings* frame_settings, JXL_BOOL lossless);
@@ -1406,7 +1423,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameLossless(
 /**
  * Sets the distance level for lossy compression: target max butteraugli
  * distance, lower = higher quality. Range: 0 .. 25.
- * 0.0 = mathematically lossless (however, use JxlEncoderSetFrameLossless
+ * 0.0 = mathematically lossless (however, use @ref JxlEncoderSetFrameLossless
  * instead to use true lossless, as setting distance to 0 alone is not the only
  * requirement). 1.0 = visually lossless. Recommended range: 0.5 .. 3.0. Default
  * value: 1.0.
@@ -1414,24 +1431,25 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameLossless(
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
  * @param distance the distance value to set.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetFrameDistance(
     JxlEncoderFrameSettings* frame_settings, float distance);
 
 /**
  * Sets the distance level for lossy compression of extra channels.
- * The distance is as in JxlEncoderSetFrameDistance (lower = higher quality).
- * If not set, or if set to the special value -1, the distance that was set with
- * JxlEncoderSetFrameDistance will be used.
+ * The distance is as in @ref JxlEncoderSetFrameDistance (lower = higher
+ * quality). If not set, or if set to the special value -1, the distance that
+ * was set with
+ * @ref JxlEncoderSetFrameDistance will be used.
  *
  * @param frame_settings set of options and metadata for this frame. Also
  * includes reference to the encoder object.
  * @param index index of the extra channel to set a distance value for.
  * @param distance the distance value to set.
- * @return JXL_ENC_SUCCESS if the operation was successful, JXL_ENC_ERROR
- * otherwise.
+ * @return ::JXL_ENC_SUCCESS if the operation was successful, @ref
+ * JXL_ENC_ERROR otherwise.
  */
 JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelDistance(
     JxlEncoderFrameSettings* frame_settings, size_t index, float distance);
@@ -1441,8 +1459,7 @@ JXL_EXPORT JxlEncoderStatus JxlEncoderSetExtraChannelDistance(
  *
  * This function takes in input a JPEG-style quality factor `quality` and
  * produces as output a `distance` value suitable to be used with @ref
- * JxlEncoderSetFrameDistance and
- * @ref JxlEncoderSetExtraChannelDistance.
+ * JxlEncoderSetFrameDistance and @ref JxlEncoderSetExtraChannelDistance.
  *
  * The `distance` value influences the level of compression, with lower values
  * indicating higher quality:
@@ -1479,10 +1496,10 @@ JXL_EXPORT float JxlEncoderDistanceFromQuality(float quality);
  * the @p source options, or set to default if @p source is NULL.
  *
  * The returned pointer is an opaque struct tied to the encoder and it will be
- * deallocated by the encoder when JxlEncoderDestroy() is called. For functions
- * taking both a @ref JxlEncoder and a @ref JxlEncoderFrameSettings, only
- * JxlEncoderFrameSettings created with this function for the same encoder
- * instance can be used.
+ * deallocated by the encoder when @ref JxlEncoderDestroy() is called. For
+ * functions taking both a @ref JxlEncoder and a @ref JxlEncoderFrameSettings,
+ * only @ref JxlEncoderFrameSettings created with this function for the same
+ * encoder instance can be used.
  *
  * @param enc encoder object.
  * @param source source options to copy initial values from, or NULL to get
@@ -1513,7 +1530,7 @@ JXL_EXPORT void JxlColorEncodingSetToLinearSRGB(
 /**
  * Enables usage of expert options.
  *
- * At the moment, the only expert option is setting an effort value of 10,
+ * At the moment, the only expert option is setting an effort value of 11,
  * which gives the best compression for pixel-lossless modes but is very slow.
  *
  * @param enc encoder object.
diff --git a/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
index e71e0aa926..ea66685dbc 100644
--- a/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
+++ b/third_party/jpeg-xl/lib/include/jxl/parallel_runner.h
@@ -46,39 +46,41 @@ extern "C" {
 
 /** Return code used in the JxlParallel* functions as return value. A value
  * of 0 means success and any other value means error. The special value
- * JXL_PARALLEL_RET_RUNNER_ERROR can be used by the runner to indicate any
+ * ::JXL_PARALLEL_RET_RUNNER_ERROR can be used by the runner to indicate any
  * other error.
  */
 typedef int JxlParallelRetCode;
 
 /**
- * General error returned by the JxlParallelRunInit function to indicate
+ * General error returned by the @ref JxlParallelRunInit function to indicate
  * an error.
  */
 #define JXL_PARALLEL_RET_RUNNER_ERROR (-1)
 
 /**
- * Parallel run initialization callback. See JxlParallelRunner for details.
+ * Parallel run initialization callback. See @ref JxlParallelRunner for details.
  *
  * This function MUST be called by the JxlParallelRunner only once, on the
- * same thread that called JxlParallelRunner, before any parallel execution.
- * The purpose of this call is to provide the maximum number of threads that the
- * JxlParallelRunner will use, which can be used by JPEG XL to allocate
+ * same thread that called @ref JxlParallelRunner, before any parallel
+ * execution. The purpose of this call is to provide the maximum number of
+ * threads that the
+ * @ref JxlParallelRunner will use, which can be used by JPEG XL to allocate
  * per-thread storage if needed.
  *
  * @param jpegxl_opaque the @p jpegxl_opaque handle provided to
- * JxlParallelRunner() must be passed here.
+ * @ref JxlParallelRunner() must be passed here.
  * @param num_threads the maximum number of threads. This value must be
  * positive.
  * @return 0 if the initialization process was successful.
  * @return an error code if there was an error, which should be returned by
- * JxlParallelRunner().
+ * @ref JxlParallelRunner().
  */
 typedef JxlParallelRetCode (*JxlParallelRunInit)(void* jpegxl_opaque,
                                                  size_t num_threads);
 
 /**
- * Parallel run data processing callback. See JxlParallelRunner for details.
+ * Parallel run data processing callback. See @ref JxlParallelRunner for
+ * details.
  *
  * This function MUST be called once for every number in the range [start_range,
  * end_range) (including start_range but not including end_range) passing this
@@ -86,11 +88,11 @@ typedef JxlParallelRetCode (*JxlParallelRunInit)(void* jpegxl_opaque,
  * different threads in parallel.
  *
  * @param jpegxl_opaque the @p jpegxl_opaque handle provided to
- * JxlParallelRunner() must be passed here.
+ * @ref JxlParallelRunner() must be passed here.
  * @param value the number in the range [start_range, end_range) of the call.
  * @param thread_id the thread number where this function is being called from.
  * This must be lower than the @p num_threads value passed to
- * JxlParallelRunInit.
+ * @ref JxlParallelRunInit.
  */
 typedef void (*JxlParallelRunFunction)(void* jpegxl_opaque, uint32_t value,
                                        size_t thread_id);
@@ -103,11 +105,12 @@ typedef void (*JxlParallelRunFunction)(void* jpegxl_opaque, uint32_t value,
  * number in the range [start_range, end_range) (including start_range but not
  * including end_range) possibly from different multiple threads in parallel.
  *
- * The JxlParallelRunner function does not need to be re-entrant. This means
- * that the same JxlParallelRunner function with the same runner_opaque
- * provided parameter will not be called from the library from either @p init or
+ * The @ref JxlParallelRunner function does not need to be re-entrant. This
+ * means that the same @ref JxlParallelRunner function with the same
+ * runner_opaque provided parameter will not be called from the library from
+ * either @p init or
  * @p func in the same decoder or encoder instance. However, a single decoding
- * or encoding instance may call the provided JxlParallelRunner multiple
+ * or encoding instance may call the provided @ref JxlParallelRunner multiple
  * times for different parts of the decoding or encoding process.
  *
  * @return 0 if the @p init call succeeded (returned 0) and no other error
@@ -120,7 +123,7 @@ typedef JxlParallelRetCode (*JxlParallelRunner)(
     void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
     JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
 
-/* The following is an example of a JxlParallelRunner that doesn't use any
+/* The following is an example of a @ref JxlParallelRunner that doesn't use any
  * multi-threading. Note that this implementation doesn't store any state
  * between multiple calls of the ExampleSequentialRunner function, so the
  * runner_opaque value is not used.
diff --git a/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
index a65015d861..c82b0bc23b 100644
--- a/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
+++ b/third_party/jpeg-xl/lib/include/jxl/resizable_parallel_runner.h
@@ -16,7 +16,7 @@
  * created can be changed after creation of the thread pool; the threads
  * (including the main thread) are re-used for every
  * ResizableParallelRunner::Runner call. Only one concurrent
- * JxlResizableParallelRunner call per instance is allowed at a time.
+ * @ref JxlResizableParallelRunner call per instance is allowed at a time.
  *
  * This is a scalable, lower-overhead thread pool runner, especially suitable
  * for data-parallel computations in the fork-join model, where clients need to
@@ -41,20 +41,20 @@
 extern "C" {
 #endif
 
-/** Parallel runner internally using std::thread. Use as JxlParallelRunner.
+/** Parallel runner internally using std::thread. Use as @ref JxlParallelRunner.
  */
 JXL_THREADS_EXPORT JxlParallelRetCode JxlResizableParallelRunner(
     void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
     JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
 
-/** Creates the runner for JxlResizableParallelRunner. Use as the opaque
+/** Creates the runner for @ref JxlResizableParallelRunner. Use as the opaque
  * runner. The runner will execute tasks on the calling thread until
  * @ref JxlResizableParallelRunnerSetThreads is called.
  */
 JXL_THREADS_EXPORT void* JxlResizableParallelRunnerCreate(
     const JxlMemoryManager* memory_manager);
 
-/** Changes the number of threads for JxlResizableParallelRunner.
+/** Changes the number of threads for @ref JxlResizableParallelRunner.
  */
 JXL_THREADS_EXPORT void JxlResizableParallelRunnerSetThreads(
     void* runner_opaque, size_t num_threads);
@@ -64,7 +64,7 @@ JXL_THREADS_EXPORT void JxlResizableParallelRunnerSetThreads(
 JXL_THREADS_EXPORT uint32_t
 JxlResizableParallelRunnerSuggestThreads(uint64_t xsize, uint64_t ysize);
 
-/** Destroys the runner created by JxlResizableParallelRunnerCreate.
+/** Destroys the runner created by @ref JxlResizableParallelRunnerCreate.
  */
 JXL_THREADS_EXPORT void JxlResizableParallelRunnerDestroy(void* runner_opaque);
 
diff --git a/third_party/jpeg-xl/lib/include/jxl/stats.h b/third_party/jpeg-xl/lib/include/jxl/stats.h
index c9359dc870..5ed440636f 100644
--- a/third_party/jpeg-xl/lib/include/jxl/stats.h
+++ b/third_party/jpeg-xl/lib/include/jxl/stats.h
@@ -23,15 +23,15 @@ extern "C" {
 /**
  * Opaque structure that holds the encoder statistics.
  *
- * Allocated and initialized with JxlEncoderStatsCreate().
- * Cleaned up and deallocated with JxlEncoderStatsDestroy().
+ * Allocated and initialized with @ref JxlEncoderStatsCreate().
+ * Cleaned up and deallocated with @ref JxlEncoderStatsDestroy().
  */
 typedef struct JxlEncoderStatsStruct JxlEncoderStats;
 
 /**
  * Creates an instance of JxlEncoderStats and initializes it.
  *
- * @return pointer to initialized JxlEncoderStats instance
+ * @return pointer to initialized @ref JxlEncoderStats instance
  */
 JXL_EXPORT JxlEncoderStats* JxlEncoderStatsCreate(void);
 
@@ -43,7 +43,7 @@ JXL_EXPORT JxlEncoderStats* JxlEncoderStatsCreate(void);
  */
 JXL_EXPORT void JxlEncoderStatsDestroy(JxlEncoderStats* stats);
 
-/** Data type for querying JxlEncoderStats object
+/** Data type for querying @ref JxlEncoderStats object
  */
 typedef enum {
   JXL_ENC_STAT_HEADER_BITS,
diff --git a/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
index 6166fe7d36..933f373ce9 100644
--- a/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
+++ b/third_party/jpeg-xl/lib/include/jxl/thread_parallel_runner.h
@@ -41,24 +41,24 @@
 extern "C" {
 #endif
 
-/** Parallel runner internally using std::thread. Use as JxlParallelRunner.
+/** Parallel runner internally using std::thread. Use as @ref JxlParallelRunner.
  */
 JXL_THREADS_EXPORT JxlParallelRetCode JxlThreadParallelRunner(
     void* runner_opaque, void* jpegxl_opaque, JxlParallelRunInit init,
     JxlParallelRunFunction func, uint32_t start_range, uint32_t end_range);
 
-/** Creates the runner for JxlThreadParallelRunner. Use as the opaque
+/** Creates the runner for @ref JxlThreadParallelRunner. Use as the opaque
  * runner.
  */
 JXL_THREADS_EXPORT void* JxlThreadParallelRunnerCreate(
     const JxlMemoryManager* memory_manager, size_t num_worker_threads);
 
-/** Destroys the runner created by JxlThreadParallelRunnerCreate.
+/** Destroys the runner created by @ref JxlThreadParallelRunnerCreate.
  */
 JXL_THREADS_EXPORT void JxlThreadParallelRunnerDestroy(void* runner_opaque);
 
 /** Returns a default num_worker_threads value for
- * JxlThreadParallelRunnerCreate.
+ * @ref JxlThreadParallelRunnerCreate.
  */
 JXL_THREADS_EXPORT size_t JxlThreadParallelRunnerDefaultNumWorkerThreads(void);
 
diff --git a/third_party/jpeg-xl/lib/include/jxl/types.h b/third_party/jpeg-xl/lib/include/jxl/types.h
index a47216f878..2538dbaa82 100644
--- a/third_party/jpeg-xl/lib/include/jxl/types.h
+++ b/third_party/jpeg-xl/lib/include/jxl/types.h
@@ -13,7 +13,6 @@
 #ifndef JXL_TYPES_H_
 #define JXL_TYPES_H_
 
-#include <jxl/jxl_export.h>
 #include <stddef.h>
 #include <stdint.h>
 
@@ -32,15 +31,17 @@ extern "C" {
 #define JXL_TRUE 1
 /** Portable @c false replacement. */
 #define JXL_FALSE 0
-/** Converts of bool-like value to either JXL_TRUE or JXL_FALSE. */
+/** Converts of bool-like value to either ::JXL_TRUE or ::JXL_FALSE. */
 #define TO_JXL_BOOL(C) (!!(C) ? JXL_TRUE : JXL_FALSE)
+/** Converts JXL_BOOL to C++ bool. */
+#define FROM_JXL_BOOL(C) (static_cast<bool>(C))
 
 /** Data type for the sample values per channel per pixel.
  */
 typedef enum {
   /** Use 32-bit single-precision floating point values, with range 0.0-1.0
    * (within gamut, may go outside this range for wide color gamut). Floating
-   * point output, either JXL_TYPE_FLOAT or JXL_TYPE_FLOAT16, is recommended
+   * point output, either ::JXL_TYPE_FLOAT or ::JXL_TYPE_FLOAT16, is recommended
    * for HDR and wide gamut images when color profile conversion is required. */
   JXL_TYPE_FLOAT = 0,
 
@@ -92,8 +93,7 @@ typedef struct {
   JxlDataType data_type;
 
   /** Whether multi-byte data types are represented in big endian or little
-   * endian format. This applies to JXL_TYPE_UINT16, JXL_TYPE_UINT32
-   * and JXL_TYPE_FLOAT.
+   * endian format. This applies to ::JXL_TYPE_UINT16 and ::JXL_TYPE_FLOAT.
    */
   JxlEndianness endianness;