Improve method documentation with examples

Author: sirreal

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

@@ -428,13 +428,35 @@ function ( WP_HTML_Token $token ): void {
 	 * Creates a fragment processor at the current node.
 	 *
 	 * HTML Fragment parsing always happens with a context node. HTML Fragment Processors can be
-	 * instantiated with a `BODY` context node via `WP_HTML_Processor::create_fragment()`.
+	 * instantiated with a `BODY` context node via `WP_HTML_Processor::create_fragment( $html )`.
 	 *
-	 * The context node may impact how a fragment of HTML is parsed. For example, when parsing
-	 * `<rect />A</rect>B`:
+	 * The context node may impact how a fragment of HTML is parsed. For example, consider the HTML
+	 * fragment `<td />Inside TD?</td>`.
 	 *
 	 * With a BODY context node results in the following tree:
 	 *
+	 *     └─#text Inside TD?
+	 *
+	 * Notice that the `<td>` tags are completely ignored.
+	 *
+	 * Compare that with an SVG context node that produces the following tree:
+	 *
+	 *     ├─svg:td
+	 *     └─#text Inside TD?
+	 *
+	 * Here, a `td` node in the `svg` namespace is created, and its self-closing flag is respected.
+	 * This is a peculiarity of parsing HTML in foreign content like SVG.
+	 *
+	 * Finally, consider the tree produced with a TABLE context node:
+	 *
+	 *     └─TBODY
+	 *       └─TR
+	 *         └─TD
+	 *           └─#text Inside TD?
+	 *
+	 * These examples demonstrate how important the context node may be when processing an HTML
+	 * fragment. Special care must be taken when processing fragments that are expected to appear
+	 * in specific contexts. SVG and TABLE are good examples, but there are others.
 	 *
 	 * @see https://html.spec.whatwg.org/multipage/parsing.html#html-fragment-parsing-algorithm
 	 *