Improve code comments around promoting CREATE option to a first class…

… suggestion

This code is particularly ambiguous. Adding a clear comment here should remove a lot of confusion as to why this particular work around is required. It is far from ideal but without decoupling `LinkContorl` from `URLInput` it is necessary.

packages/block-editor/src/components/link-control/index.js

@@ -198,7 +198,7 @@ function LinkControl( {
 	};
 
 	const handleEntitySearch = async ( val, args ) => {
-		const results = await Promise.all( [
+		let results = await Promise.all( [
 			fetchSearchSuggestions( val, {
 				...( args.isInitialSuggestions ? { perPage: 3 } : {} ),
 			} ),
@@ -210,9 +210,18 @@ function LinkControl( {
 		// If it's potentially a URL search then concat on a URL search suggestion
 		// just for good measure. That way once the actual results run out we always
 		// have a URL option to fallback on.
-		const rtn = couldBeURL && ! args.isInitialSuggestions ? results[ 0 ].concat( results[ 1 ] ) : results[ 0 ];
-
-		return rtn.concat( {
+		results = couldBeURL && ! args.isInitialSuggestions ? results[ 0 ].concat( results[ 1 ] ) : results[ 0 ];
+
+		// Here we append a faux suggestion to represent a "CREATE" option. This
+		// is detected in the rendering of the search results and handeled as a
+		// special case. This is currently necessary because the suggestions
+		// dropdown will only appear if there are valid suggestions and
+		// therefore unless the create option is a suggestion it will not
+		// display in scenarios where there are no results returned from the
+		// API. In addition promoting CREATE to a first class suggestion affords
+		// the a11y benefits afforded by `URLInput` to all suggestions (eg:
+		// keyboard handling, ARIA roles...etc).
+		return results.concat( {
 			id: '-2',
 			? results[ 0 ].concat( results[ 1 ] )
 			title: '',
@@ -222,8 +231,10 @@ function LinkControl( {
 	};
 
 	/**
+	 * Detmineres which type of search handler to use based on the users input.
 	 * Cancels editing state and marks that focus may need to be restored after
 	 * the next render, if focus was within the wrapper when editing finished.
+	 * else a API search should made for matching Entities.
 	 */
 	function stopEditing() {
 		isEndingEditWithFocus.current =