refactor(ivy): Update query-related comments

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

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,8 @@ 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, `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<{}>;