improve collection and collectionGroup JSDoc

codeForDoc/src/quick_start/query.ts

@@ -4,7 +4,7 @@ import { getDocs, query, where, orderBy, limit } from 'firelordjs'
 // filter documents
 getDocs(
 	query(
-		example.collection(),
+		example.collection(), // or example.collectionGroup()
 		where('f.h', '>', 1010),
 		orderBy('f.h'),
 		limit(10)
@@ -25,3 +25,8 @@ getDocs(
 		// similar to docSnapshot of getDoc
 	})
 })
+
+// get all collection documents
+getDocs(
+	example.collection() // or example.collectionGroup()
+)

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "firelordjs",
-	"version": "2.6.4",
+	"version": "2.6.5",
 	"description": "🔥 High Precision Typescript Wrapper for Firestore Web, Providing Unparalleled Type Safe and Dev Experience",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

src/types/firelord.ts

@@ -16,19 +16,15 @@ type Doc_<T extends MetaType> = {
 }
 
 type Collection_<T extends MetaType> = {
-	/**
-	 * Gets a `CollectionReference` instance that refers to the collection at
-	 * the specified absolute path.
-	 *
-	 * @param documentIds - all the docID(s) needed to build this collection path.
-	 * @returns The `CollectionReference` instance.
-	 */
 	collection: Collection<T>
 }
 
 type CollectionGroup_<T extends MetaType> = {
 	/**
-	 * @returns — The created Query.
+	 *  related documentations:
+	 *  - {@link https://firelordjs.com/quick_start/#query query}
+	 *  - {@link https://firelordjs.com/quick_start/#onsnapshot onSnapshot}
+	 * @returns — The created {@link Query}.
 	 */
 	collectionGroup: () => Query<T>
 }

src/types/refs/collection.ts

@@ -6,8 +6,8 @@ import { DocumentReference } from './doc'
 import { Query } from './query'
 
 /**
- * A `CollectionReference` object can be used for adding documents, getting
- * document references, and querying for documents (using {@link query}).
+ * A {@link CollectionReference} object can be used for adding documents, getting
+ * {@link DocumentReference}, and querying for documents (using {@link Query}).
  */
 export interface CollectionReference<T extends MetaType> extends Query<T> {
 	/** The type of this Firestore reference. */
@@ -20,32 +20,38 @@ export interface CollectionReference<T extends MetaType> extends Query<T> {
 	 */
 	get path(): T['collectionPath']
 	/**
-	 * A reference to the containing `DocumentReference` if this is a
-	 * subcollection. If this isn't a subcollection, the reference is null.
+	 * A reference to the containing parent {@link DocumentReference} if this is a
+	 * sub-collection. If this isn't a sub-collection, the reference is null.
 	 */
 	get parent(): T['parent'] extends MetaType
 		? DocumentReference<T['parent']>
 		: null
 }
 
-export type CollectionCreator =
+export type CollectionCreator = <T extends MetaType>(
+	fStore: Firestore,
+	...collectionIDs: GetOddOrEvenSegments<T['collectionPath'], 'Odd'>
+) => Collection<T>
+
+export type Collection<T extends MetaType> = {
 	/**
-	 * Gets a `CollectionReference` instance that refers to the collection at
+	 * Gets a {@link CollectionReference} instance that refers to the collection at
 	 * the specified absolute path.
 	 *
-	 * @param documentIds - all the docID(s) needed to build this collection path.
-	 * @returns The `CollectionReference` instance.
+	 *  related documentations:
+	 *  - {@link https://firelordjs.com/guides/metatype child meta type}
+	 *  - {@link https://firelordjs.com/quick_start#operations operation}
+	 * @param documentIds
+	 *  All the docID(s) needed to build this document path, eg
+	 *  - for top-collection: example.collection()
+	 *  - for sub-collection: example.collection(GrandParentDocId, ParentsDocId)
+	 *
+	 * @returns The {@link CollectionReference} instance.
 	 */
-	<T extends MetaType>(
-		fStore: Firestore,
-		...collectionIDs: GetOddOrEvenSegments<T['collectionPath'], 'Odd'>
-	) => Collection<T>
-
-export type Collection<T extends MetaType> = <
-	D extends GetOddOrEvenSegments<T['collectionPath'], 'Even'>
->(
-	...documentIDs: D extends never ? D : IsValidDocIDLoop<D>
-) => CollectionReference<T>
+	<D extends GetOddOrEvenSegments<T['collectionPath'], 'Even'>>(
+		...documentIDs: D extends never ? D : IsValidDocIDLoop<D>
+	): CollectionReference<T>
+}
 
 export type GetCollectionIds<T extends MetaType> = GetOddOrEvenSegments<
 	T['collectionPath'],

src/types/refs/collectionGroup.ts

@@ -3,18 +3,17 @@ import { Firestore } from '../alias'
 import { Query } from './query'
 
 /**
- * A `CollectionGroup` refers to all documents that are contained in a
- * collection or subcollection with a specific collection ID.
+ * A {@link CollectionGroup} refers to all documents that are contained in a
+ * collection or sub-collection with a specific collection ID.
  */
-export interface CollectionGroupReference<T extends MetaType> extends Query<T> {
+export interface CollectionGroup<T extends MetaType> extends Query<T> {
 	/** The type of this Firestore reference. */
 	readonly type: 'query'
 }
 
 export type CollectionGroupCreator = <T extends MetaType>(
 	fStore: Firestore,
 	collectionID: T['collectionID']
-) => /**
- * @returns — The created Query.
- */
-() => CollectionGroupReference<T>
+) => {
+	(): CollectionGroup<T>
+}