properties: add extra usage documentation

include/avif/avif.h

@@ -863,7 +863,14 @@ AVIF_API void avifImageFreePlanes(avifImage * image, avifPlanesFlags planes);
 AVIF_API void avifImageStealPlanes(avifImage * dstImage, avifImage * srcImage, avifPlanesFlags planes);
 
 // Add arbitrary (opaque) properties to the image
+// Use of these functions for known properties and boxes (e.g. ispe or meta) will likely result in
+// invalid files, and should be avoided.
+// If creating a ItemFullProperty, the version and flags values should be provided as the first four bytes of
+// the data argument, and accounted for in the dataSize.
 AVIF_API avifResult avifImageAddOpaqueProperty(avifImage * image, const uint8_t boxtype[4], const uint8_t * data, size_t dataSize);
+// This version adds an ItemProperty (or ItemFullProperty if version and flags are provided in data argument), using
+// the user extension (uuid) mechanism, see ISO/IEC 14496-12:2022 Section 4.2. The box type is set to 'uuid' and
+// does not need to be specified.
 AVIF_API avifResult avifImageAddUUIDProperty(avifImage * image, const uint8_t uuid[16], const uint8_t * data, size_t dataSize);
 
 // ---------------------------------------------------------------------------