refactor(ivy): Update query-related comments (#29342)

Just updating comments in query-related things to make it easier for the next person that has to grok this for the first time.

Also adds a demo from @mhevery to one of the query specs

Related #29031

PR Close #29342

packages/core/src/linker/query_list.ts

@@ -93,20 +93,33 @@ export class QueryList<T>/* implements Iterable<T> */ {
     return this._results.some(fn);
   }
 
+  /**
+   * Returns a copy of the internal results list as an Array.
+   */
   toArray(): T[] { return this._results.slice(); }
 
   [getSymbolIterator()](): Iterator<T> { return (this._results as any)[getSymbolIterator()](); }
 
   toString(): string { return this._results.toString(); }
 
-  reset(res: Array<T|any[]>): void {
-    this._results = flatten(res);
+  /**
+   * Updates the stored data of the query list, and resets the `dirty` flag to `false`, so that
+   * on change detection, it will not notify of changes to the queries, unless a new change
+   * occurs.
+   *
+   * @param resultsTree The results tree to store
+   */
+  reset(resultsTree: Array<T|any[]>): void {
+    this._results = depthFirstFlatten(resultsTree);
     (this as{dirty: boolean}).dirty = false;
     (this as{length: number}).length = this._results.length;
     (this as{last: T}).last = this._results[this.length - 1];
     (this as{first: T}).first = this._results[0];
   }
 
+  /**
+   * Triggers a change event by emitting on the `changes` {@link EventEmitter}.
+   */
   notifyOnChanges(): void { (this.changes as EventEmitter<any>).emit(this); }
 
   /** internal */
@@ -119,9 +132,9 @@ export class QueryList<T>/* implements Iterable<T> */ {
   }
 }
 
-function flatten<T>(list: Array<T|T[]>): T[] {
+function depthFirstFlatten<T>(list: Array<T|T[]>): T[] {
   return list.reduce((flat: any[], item: T | T[]): T[] => {
-    const flatItem = Array.isArray(item) ? flatten(item) : item;
+    const flatItem = Array.isArray(item) ? depthFirstFlatten(item) : item;
     return (<T[]>flat).concat(flatItem);
   }, []);
 }