Provide a custom decoder for strings coming from HTML attributes and
markup. This custom decoder is necessary because of deficiencies in
PHP's `html_entity_decode()` function:

 - It isn't aware of 720 of the possible named character references in
   HTML, leaving many out that should be translated.

 - It isn't able to decode character references in data segments where
   the final semicolon is missing, or when there are ambiguous
   characters after the reference name but before the semicolon.
   This one is complicated: refer to the HTML5 specification to clarify.

This decoder will also provide some conveniences, such as making a
single-pass and interruptable decode operation possible. This will
provide a number of opportunities to optimize detection and decoding
of things like value prefixes, and whether a value contains a given
substring.

…decoder

?string (nullable string) was used for these types.
The type should be string, optionality can appear in the param description
but is derived from a default argument.

?Type is a nullable Type, not an optional parameter. Identify optional
parameters in the @param description.

Instead of a nullable parameter that updates to `0` in the body of the
function when null, use a default argument `0`, update the @param type
and remove the null check and set from the function body.

Add mixed case and non-matching test cases

Update the parameter name and description to align with the descriptions
of analogous parameters used in WP_Token_Map methods.

…decoder