refactor(ivy): Update query-related comments (angular#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 angular#29031

PR Close angular#29342

Author: benlesh

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);
   }, []);
 }

packages/core/src/render3/query.ts

@@ -365,7 +365,9 @@ export function query<T>(
 /**
  * Refreshes a query by combining matches from all active views and removing matches from deleted
  * views.
- * Returns true if a query got dirty during change detection, false otherwise.
+ *
+ * @returns `true` if a query got dirty during change detection or if this is a static query
+ * resolving in creation mode, `false` otherwise.
  */
 export function queryRefresh(queryList: QueryList<any>): boolean {
   const queryListImpl = (queryList as any as QueryList_<any>);

packages/core/test/render3/query_spec.ts

@@ -1603,6 +1603,7 @@ describe('query', () => {
          });
 
       // https://stackblitz.com/edit/angular-7vvo9j?file=src%2Fapp%2Fapp.component.ts
+      // https://stackblitz.com/edit/angular-xzwp6n
       it('should report results when the same TemplateRef is inserted into different ViewContainerRefs',
          () => {
            let tpl: TemplateRef<{}>;

tools/public_api_guard/core/core.d.ts

@@ -721,7 +721,7 @@ export declare class QueryList<T> {
     map<U>(fn: (item: T, index: number, array: T[]) => U): U[];
     notifyOnChanges(): void;
     reduce<U>(fn: (prevValue: U, curValue: T, curIndex: number, array: T[]) => U, init: U): U;
-    reset(res: Array<T | any[]>): void;
+    reset(resultsTree: Array<T | any[]>): void;
     setDirty(): void;
     some(fn: (value: T, index: number, array: T[]) => boolean): boolean;
     toArray(): T[];