Add note linking parse_blocks and block_scanner

Author: dmsnell

src/wp-includes/blocks.php

@@ -2362,6 +2362,17 @@ function render_block( $parsed_block ) {
 /**
  * Parses blocks out of a content string.
  *
+ * Given an HTML document, this function fully-parses block content, producing
+ * a tree of blocks and their contents, as well as top-level non-block content,
+ * which will appear as a block with no `blockName`.
+ *
+ * This function can be memory heavy for certain documents, particularly those
+ * with deeply-nested blocks or blocks with extensive attribute values. Further,
+ * this function must parse an entire document in one atomic operation.
+ *
+ * If the entire parsed document is not necessary, consider using {@see WP_Block_Scanner}
+ * instead, as it provides a streaming and low-overhead interface for finding blocks.
+ *
  * @since 5.0.0
  *
  * @param string $content Post content.

src/wp-includes/class-wp-block-scanner.php

@@ -15,6 +15,9 @@
  *
  * For usage, jump straight to {@see self::next_delimiter}.
  *
+ * If it’s necessary to end up with a fully-parsed document anyway,
+ * consider using {@see parse_blocks()} instead.
+ *
  * @todo Add wildcard matching to namespace and name in ::opens_block(), ::is_block_type, etc…
  * @todo Is "freeform" the best name since it can also appear inside blocks? Maybe "html" or "text" or "non-block content".
  * @todo Add optimized lookup for blocks of a known name