Document the decoder functions for text nodes and attribute values.

Author: dmsnell

src/wp-includes/html-api/class-wp-html-decoder.php

@@ -23,7 +23,7 @@ class WP_HTML_Decoder {
 	 *     true   === WP_HTML_Decoder::attribute_starts_with( $value, 0, null, 'http:', 'case-insensitive' );
 	 *     false  === WP_HTML_Decoder::attribute_starts_with( $value, 0, null, 'https:', 'case-insensitive' );
 	 *
-	 * The `$value_at` and `$value_length` parameters may be used to avoid string allocations when the
+	 * Use the `$value_at` and `$value_length` parameters to avoid string allocations when the
 	 * attribute value is found within a larger string.
 	 *
 	 * Example:
@@ -41,13 +41,14 @@ class WP_HTML_Decoder {
 	 *     false === WP_HTML_Decode::attribute_starts_with( $html, $href[0], $href[1], 'http://', 'case-insensitive' );
 	 *     false === WP_HTML_Decode::attribute_starts_with( $html, $title[0], $title[1], '&copy' );
 	 *
+	 * @since 6.6.0
+	 *
 	 * @param string  $raw_haystack     String containing the raw non-decoded attribute value.
 	 * @param int     $value_at         How many bytes into the haystack where the attribute value begins.
 	 * @param int     $value_length     How many bytes the attribute value spans.
 	 *                                  Passing `null` indicates that the value spans to the end of the string.
 	 * @param string  $search_text      Does the attribute value start with this plain string.
 	 * @param ?string $case_sensitivity Set to `case-insensitive` to ignore ASCII case when matching.
-	 *
 	 * @return bool Whether the attribute value starts with the given string.
 	 */
 	public static function attribute_starts_with( $raw_haystack, $value_at, $value_length, $search_text, $case_sensitivity = 'case-sensitive' ) {
@@ -91,14 +92,74 @@ public static function attribute_starts_with( $raw_haystack, $value_at, $value_l
 		return true;
 	}
 
+	/**
+	 * Returns a string containing the decoded value of a given HTML text node,
+	 * supplied with the optional starting byte offset and length of node.
+	 *
+	 * Example:
+	 *
+	 *     '“😄”' === WP_HTML_Decode::decode_text_node( '“😄&#x94' );
+	 *
+	 * Use the `$at` and `$length` parameters to avoid string allocations when the
+	 * text node is found within a larger string. Note that the `$at` and `$length`
+	 * values should specify the full span of the text node and not end before the
+	 * text node ends. This is because the rules for decoding character references
+	 * change at the end of a string vs. in the middle of one.
+	 *
+	 * Example:
+	 *
+	 *     'Read more…' === WP_HTML_Decoder::decode_text_node( '<a>Read more&hellip;</a>', 3, 17 );
+	 *
+	 * @since 6.6.0
+	 *
+	 * @param string $text   Text containing raw and non-decoded text node to decode.
+	 * @param ?int   $at     Byte offset into `$text` where text node begins. Defaults to start of `$text`.
+	 * @param ?int   $length How many bytes the text node spans. Defaults to end of `$text`.
+	 * @return string Decoded value of given text node.
+	 */
 	public static function decode_text_node( $text, $at = 0, $length = null ) {
 		return static::decode( true, $text, $at, $length );
 	}
 
+	/**
+	 * Returns a string containing the decoded value of a given HTML attribute,
+	 * supplied with the optional starting byte offset and length of attribute value.
+	 *
+	 * Example:
+	 *
+	 *     '“😄”' === WP_HTML_Decode::decode_attribute( '&#x93;&#x1f604;&#x94' );
+	 *
+	 * Use the `$at` and `$length` parameters to avoid string allocations when the
+	 * attribute value is found within a larger string. Note that the `$at` and
+	 * `$length` values should specify the full span of the attribute value and not
+	 * end before the attribute value ends. This is because the rules for decoding
+	 * character references change at the end of a string vs. in the middle of one.
+	 *
+	 * Example:
+	 *
+	 *     $link = WP_HTML_Decoder::decode_attribute( '<a href="https&colon;//wordpress.org">', 9, 27 );
+	 *     $link === 'https://wordpress.org';
+	 *
+	 * @since 6.6.0
+	 *
+	 * @param string $text   Text containing raw and non-decoded attribute value to decode.
+	 * @param ?int   $at     Byte offset into `$text` where attribute value begins. Defaults to start of `$text`.
+	 * @param ?int   $length How many bytes the attribute value spans. Defaults to end of `$text`.
+	 * @return string Decoded value of given attribute value.
+	 */
 	public static function decode_attribute( $text, $at = 0, $length = null ) {
 		return static::decode( false, $text, $at, $length );
 	}
 
+	/**
+	 * Decodes a span of HTML text, respecting the ambiguous ampersand rule.
+	 *
+	 * @param $allow_ambiguous_ampersands
+	 * @param $text
+	 * @param $at
+	 * @param $length
+	 * @return mixed|string
+	 */
 	public static function decode( $allow_ambiguous_ampersands, $text, $at = 0, $length = null ) {
 		$decoded = '';
 		$end     = isset( $length ) ? $at + $length : strlen( $text );