Corrected and improved comments.

Author: MarkDuckworth

packages/firestore/src/lite-api/query.ts

@@ -127,19 +127,20 @@ export function query<T>(
 }
 
 /**
- * A `QueryFilterConstraint` is used to narrow the set of documents returned by a
- * Firestore query by filtering on one or more document fields. `QueryFilterConstraint`s are created by invoking {@link where},
- * {@link or} or {@link and} and
- * can then be passed to {@link query} to create a new query instance that
- * also contains this `QueryFilterConstraint`.
+ * A `QueryFilterConstraint` is used to narrow the set of documents returned by
+ * a Firestore query by filtering on one or more document fields.
+ * `QueryFilterConstraint`s are created by invoking {@link where}, {@link or} or
+ * {@link and} and can then be passed to {@link query} to create a new query
+ * instance that also contains this `QueryFilterConstraint`.
  */
 export abstract class QueryFilterConstraint extends QueryConstraint {
   abstract _parse<T>(query: Query<T>): Filter;
 }
 
 /**
- * A `QueryFieldFilterConstraint` is used to narrow the set of documents returned by a
- * Firestore query by filtering on one document field. `QueryFieldFilterConstraint`s are created by invoking {@link where}  and
+ * A `QueryFieldFilterConstraint` is used to narrow the set of documents
+ * returned by a Firestore query by filtering on one document field.
+ * `QueryFieldFilterConstraint`s are created by invoking {@link where}  and
  * can then be passed to {@link query} to create a new query instance that
  * also contains this `QueryFieldFilterConstraint`.
  */
@@ -205,9 +206,9 @@ export type WhereFilterOp =
   | 'not-in';
 
 /**
- * Creates a {@link QueryFieldFilterConstraint} that enforces that documents must contain the
- * specified field and that the value should satisfy the relation constraint
- * provided.
+ * Creates a {@link QueryFieldFilterConstraint} that enforces that documents
+ * must contain the specified field and that the value should satisfy the
+ * relation constraint provided.
  *
  * @param fieldPath - The path to compare
  * @param opStr - The operation string (e.g "&lt;", "&lt;=", "==", "&lt;",
@@ -226,11 +227,12 @@ export function where(
 }
 
 /**
- * A `QueryCompositeFilterConstraint` is used to narrow the set of documents returned by a
- * Firestore query by performing the logical OR or AND of multiple {@link QueryFieldFilterConstraint} or {@link QueryCompositeFilterConstraint}.
- * `QueryCompositeFilterConstraint`s are created by invoking {@link or} or {@link and} and
- * can then be passed to {@link query} to create a new query instance that
- * also contains this `QueryCompositeFilterConstraint`.
+ * A `QueryCompositeFilterConstraint` is used to narrow the set of documents
+ * returned by a Firestore query by performing the logical OR or AND of multiple
+ * {@link QueryFieldFilterConstraint} or {@link QueryCompositeFilterConstraint}.
+ * `QueryCompositeFilterConstraint`s are created by invoking {@link or} or
+ * {@link and} and can then be passed to {@link query} to create a new query
+ * instance that also contains this `QueryCompositeFilterConstraint`.
  */
 export class QueryCompositeFilterConstraint extends QueryFilterConstraint {
   protected constructor(
@@ -264,7 +266,8 @@ export class QueryCompositeFilterConstraint extends QueryFilterConstraint {
   _apply<T>(query: Query<T>): Query<T> {
     const parsedFilter = this._parse(query);
     if (parsedFilter.getFilters().length === 0) {
-      // Return the existing query if not adding any more filters (e.g. an empty composite filter).
+      // Return the existing query if not adding any more filters (e.g. an empty
+      // composite filter).
       return query;
     }
     validateNewFilter(query._query, parsedFilter);
@@ -289,8 +292,9 @@ export class QueryCompositeFilterConstraint extends QueryFilterConstraint {
  * Creates a {@link QueryCompositeFilterConstraint} that performs a logical OR
  * of all the provided {@link QueryFilterConstraint}.
  *
- * @param queryConstraints - Optional. The {@link queryConstraints} for OR operation. These must be
- * created with calls to {@link where}, {@link or}, or {@link and}.
+ * @param queryConstraints - Optional. The {@link queryConstraints} for OR
+ * operation. These must be created with calls to {@link where}, {@link or}, or
+ * {@link and}.
  * @returns The created {@link QueryCompositeFilterConstraint}.
  */
 export function or(
@@ -311,8 +315,9 @@ export function or(
  * Creates a {@link QueryCompositeFilterConstraint} that performs a logical AND
  * of all the provided {@link QueryFilterConstraint}.
  *
- * @param queryConstraints - Optional. The {@link queryConstraints} for AND operation. These must be
- * created with calls to {@link where}, {@link or}, or {@link and}.
+ * @param queryConstraints - Optional. The {@link queryConstraints} for AND
+ * operation. These must be created with calls to {@link where}, {@link or}, or
+ * {@link and}.
  * @returns The created {@link QueryCompositeFilterConstraint}.
  */
 export function and(
@@ -331,10 +336,12 @@ export function and(
 
 /**
  * A `QueryOrderByConstraint` is used to sort the set of documents returned by a
- * Firestore query.
- * `QueryOrderByConstraint`s are created by invoking {@link orderBy} and
- * can then be passed to {@link query} to create a new query instance that
- * also contains this `QueryOrderByConstraint`.
+ * Firestore query. `QueryOrderByConstraint`s are created by invoking
+ * {@link orderBy} and can then be passed to {@link query} to create a new query
+ * instance that also contains this `QueryOrderByConstraint`.
+ *
+ * Note: Documents that do not contain the orderBy field will not be present in
+ * the query result.
  */
 export class QueryOrderByConstraint extends QueryConstraint {
   readonly type = 'orderBy';
@@ -373,6 +380,9 @@ export type OrderByDirection = 'desc' | 'asc';
  * Creates a {@link QueryOrderByConstraint} that sorts the query result by the
  * specified field, optionally in descending order instead of ascending.
  *
+ * Note: Documents that do not contain the specified field will not be present
+ * in the query result.
+ *
  * @param fieldPath - The field to sort by.
  * @param directionStr - Optional direction to sort by ('asc' or 'desc'). If
  * not specified, order will be ascending.
@@ -388,11 +398,11 @@ export function orderBy(
 }
 
 /**
- * A `QueryLimitConstraint` is used to limit the number of documents returned by a
- * Firestore query.
- * `QueryLimitConstraint`s are created by invoking {@link limit} or {@link limitToLast} and
- * can then be passed to {@link query} to create a new query instance that
- * also contains this `QueryLimitConstraint`.
+ * A `QueryLimitConstraint` is used to limit the number of documents returned by
+ * a Firestore query.
+ * `QueryLimitConstraint`s are created by invoking {@link limit} or
+ * {@link limitToLast} and can then be passed to {@link query} to create a new
+ * query instance that also contains this `QueryLimitConstraint`.
  */
 export class QueryLimitConstraint extends QueryConstraint {
   protected constructor(
@@ -421,7 +431,8 @@ export class QueryLimitConstraint extends QueryConstraint {
 }
 
 /**
- * Creates a {@link QueryLimitConstraint} that only returns the first matching documents.
+ * Creates a {@link QueryLimitConstraint} that only returns the first matching
+ * documents.
  *
  * @param limit - The maximum number of items to return.
  * @returns The created {@link QueryLimitConstraint}.
@@ -432,7 +443,8 @@ export function limit(limit: number): QueryLimitConstraint {
 }
 
 /**
- * Creates a {@link QueryLimitConstraint} that only returns the last matching documents.
+ * Creates a {@link QueryLimitConstraint} that only returns the last matching
+ * documents.
  *
  * You must specify at least one `orderBy` clause for `limitToLast` queries,
  * otherwise an exception will be thrown during execution.
@@ -446,11 +458,11 @@ export function limitToLast(limit: number): QueryLimitConstraint {
 }
 
 /**
- * A `QueryStartAtConstraint` is used to exclude documents from the start of a result set returned by a
- * Firestore query.
- * `QueryStartAtConstraint`s are created by invoking {@link (startAt:1)} or {@link (startAfter:1)} and
- * can then be passed to {@link query} to create a new query instance that
- * also contains this `QueryStartAtConstraint`.
+ * A `QueryStartAtConstraint` is used to exclude documents from the start of a
+ * result set returned by a Firestore query.
+ * `QueryStartAtConstraint`s are created by invoking {@link (startAt:1)} or
+ * {@link (startAfter:1)} and can then be passed to {@link query} to create a
+ * new query instance that also contains this `QueryStartAtConstraint`.
  */
 export class QueryStartAtConstraint extends QueryConstraint {
   protected constructor(
@@ -485,10 +497,10 @@ export class QueryStartAtConstraint extends QueryConstraint {
 }
 
 /**
- * Creates a {@link QueryStartAtConstraint} that modifies the result set to start at the
- * provided document (inclusive). The starting position is relative to the order
- * of the query. The document must contain all of the fields provided in the
- * `orderBy` of this query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start at the provided document (inclusive). The starting position is relative
+ * to the order of the query. The document must contain all of the fields
+ * provided in the `orderBy` of this query.
  *
  * @param snapshot - The snapshot of the document to start at.
  * @returns A {@link QueryStartAtConstraint} to pass to `query()`.
@@ -497,9 +509,9 @@ export function startAt(
   snapshot: DocumentSnapshot<unknown>
 ): QueryStartAtConstraint;
 /**
- * Creates a {@link QueryStartAtConstraint} that modifies the result set to start at the
- * provided fields relative to the order of the query. The order of the field
- * values must match the order of the order by clauses of the query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start at the provided fields relative to the order of the query. The order of
+ * the field values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to start this query at, in order
  * of the query's order by.
@@ -517,10 +529,10 @@ export function startAt(
 }
 
 /**
- * Creates a {@link QueryStartAtConstraint} that modifies the result set to start after the
- * provided document (exclusive). The starting position is relative to the order
- * of the query. The document must contain all of the fields provided in the
- * orderBy of the query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start after the provided document (exclusive). The starting position is
+ * relative to the order of the query. The document must contain all of the
+ * fields provided in the orderBy of the query.
  *
  * @param snapshot - The snapshot of the document to start after.
  * @returns A {@link QueryStartAtConstraint} to pass to `query()`
@@ -529,9 +541,9 @@ export function startAfter(
   snapshot: DocumentSnapshot<unknown>
 ): QueryStartAtConstraint;
 /**
- * Creates a {@link QueryStartAtConstraint} that modifies the result set to start after the
- * provided fields relative to the order of the query. The order of the field
- * values must match the order of the order by clauses of the query.
+ * Creates a {@link QueryStartAtConstraint} that modifies the result set to
+ * start after the provided fields relative to the order of the query. The order
+ * of the field values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to start this query after, in order
  * of the query's order by.
@@ -549,11 +561,11 @@ export function startAfter(
 }
 
 /**
- * A `QueryEndAtConstraint` is used to exclude documents from the end of a result set returned by a
- * Firestore query.
- * `QueryEndAtConstraint`s are created by invoking {@link (endAt:1)} or {@link (endBefore:1)} and
- * can then be passed to {@link query} to create a new query instance that
- * also contains this `QueryEndAtConstraint`.
+ * A `QueryEndAtConstraint` is used to exclude documents from the end of a
+ * result set returned by a Firestore query.
+ * `QueryEndAtConstraint`s are created by invoking {@link (endAt:1)} or
+ * {@link (endBefore:1)} and can then be passed to {@link query} to create a new
+ * query instance that also contains this `QueryEndAtConstraint`.
  */
 export class QueryEndAtConstraint extends QueryConstraint {
   protected constructor(
@@ -588,10 +600,10 @@ export class QueryEndAtConstraint extends QueryConstraint {
 }
 
 /**
- * Creates a {@link QueryEndAtConstraint} that modifies the result set to end before the
- * provided document (exclusive). The end position is relative to the order of
- * the query. The document must contain all of the fields provided in the
- * orderBy of the query.
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end
+ * before the provided document (exclusive). The end position is relative to the
+ * order of the query. The document must contain all of the fields provided in
+ * the orderBy of the query.
  *
  * @param snapshot - The snapshot of the document to end before.
  * @returns A {@link QueryEndAtConstraint} to pass to `query()`
@@ -600,9 +612,9 @@ export function endBefore(
   snapshot: DocumentSnapshot<unknown>
 ): QueryEndAtConstraint;
 /**
- * Creates a {@link QueryEndAtConstraint} that modifies the result set to end before the
- * provided fields relative to the order of the query. The order of the field
- * values must match the order of the order by clauses of the query.
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end
+ * before the provided fields relative to the order of the query. The order of
+ * the field values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to end this query before, in order
  * of the query's order by.
@@ -620,9 +632,9 @@ export function endBefore(
 }
 
 /**
- * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at the
- * provided document (inclusive). The end position is relative to the order of
- * the query. The document must contain all of the fields provided in the
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at
+ * the provided document (inclusive). The end position is relative to the order
+ * of the query. The document must contain all of the fields provided in the
  * orderBy of the query.
  *
  * @param snapshot - The snapshot of the document to end at.
@@ -632,8 +644,8 @@ export function endAt(
   snapshot: DocumentSnapshot<unknown>
 ): QueryEndAtConstraint;
 /**
- * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at the
- * provided fields relative to the order of the query. The order of the field
+ * Creates a {@link QueryEndAtConstraint} that modifies the result set to end at
+ * the provided fields relative to the order of the query. The order of the field
  * values must match the order of the order by clauses of the query.
  *
  * @param fieldValues - The field values to end this query at, in order