Add more commentary about quirks
@@ -30,12 +30,31 @@ pub const decoder_workbuf_len_max_incl_worst_case base.u64 = 1
// --------
-// Quirks.
+// Quirks are configuration options that let Wuffs more closely match other
+// codec implementations.
+//
+// Some codecs and file formats are more tightly specified than others. When a
+// spec doesn't fully dictate how to treat malformed files, different codec
+// implementations have disagreed on whether to accept it (e.g. whether they
+// follow Postel's Principle of "be liberal in what you accept") and if so, how
+// to interpret it. Some implementations also raise those decisions to the
+// application level, not the library level: "provide mechanism, not policy".
+//
+// For example, in an animated image, the first frame might not fill out the
+// entire image, and different implementations choose a different default color
+// for the outside pixels: opaque black, transparent black, or something else.
+//
+// Wuffs, out of the box, makes particular choices (typically mimicking the de
+// facto canonical implementation), but enabling various quirks result in
+// different choices. In particular, quirks are useful in regression testing
+// that Wuffs and another implementation produce the same output for the same
+// input, even for malformed input.
+//
+// In terms of the Wuffs API, each quirk is assigned a uint32 value. A base38
+// (github.com/google/wuffs/lib/base38) value can fit in 21 bits. Leaving the
+// high bit of a uint32 reserved, the low 10 bits hold a package-specific
+// enumeration: the base38 value acts as a namespace.
//
-// A base38 (github.com/google/wuffs/lib/base38) value can fit in 21 bits.
-// Leaving the high bit of a uint32 reserved, the low 10 bits can be used for
-// package-specific quirk constants: the base38 value acts as a namespace.
-
// The base38 encoding of "gif " is 0xF8586.
// When this quirk is enabled, when skipping over frames, the number of frames
