Fluent API documentation (new PR)

src/db/list_doc.rs

@@ -27,9 +27,12 @@ pub struct FirestoreListDocParams {
     pub return_only_fields: Option<Vec<String>>,
 }
 
+/// The result of a list documents call
 #[derive(Debug, PartialEq, Clone, Builder)]
 pub struct FirestoreListDocResult {
+    /// the list of documents
     pub documents: Vec<Document>,
+    /// the next page token
     pub page_token: Option<String>,
 }
 

src/db/query_models.rs

@@ -262,9 +262,12 @@ impl From<&FirestoreQueryParams> for StructuredQuery {
     }
 }
 
+/// Used for sorting
 #[derive(Debug, Eq, PartialEq, Clone, Builder)]
 pub struct FirestoreQueryOrder {
+    /// The field name to order by.
     field_name: String,
+    /// The direction to order by.
     direction: FirestoreQueryDirection,
 }
 
@@ -303,6 +306,7 @@ impl From<&FirestoreQueryOrder> for structured_query::Order {
     }
 }
 
+/// Specifies the order to sort by.
 #[derive(Debug, Eq, PartialEq, Clone)]
 pub enum FirestoreQueryDirection {
     Ascending,

src/fluent_api/insert_builder.rs

@@ -19,6 +19,7 @@ where
         Self { db }
     }
 
+    /// Specifies the collection to insert into
     #[inline]
     pub fn into(self, collection_id: &str) -> FirestoreInsertDocIdBuilder<'a, D> {
         FirestoreInsertDocIdBuilder::new(self.db, collection_id.to_string())
@@ -43,6 +44,7 @@ where
         Self { db, collection_id }
     }
 
+    /// Set the document id
     #[inline]
     pub fn document_id<S>(self, document_id: S) -> FirestoreInsertDocObjBuilder<'a, D>
     where
@@ -55,6 +57,7 @@ where
         )
     }
 
+    /// Automatically generate a document id
     #[inline]
     pub fn generate_document_id(self) -> FirestoreInsertDocObjBuilder<'a, D> {
         FirestoreInsertDocObjBuilder::new(self.db, self.collection_id, None)
@@ -116,6 +119,7 @@ where
         }
     }
 
+    /// Set the document content
     #[inline]
     pub fn document(self, document: Document) -> FirestoreInsertDocExecuteBuilder<'a, D> {
         FirestoreInsertDocExecuteBuilder::new(
@@ -181,6 +185,7 @@ where
         }
     }
 
+    /// Execute the insert operation
     pub async fn execute(self) -> FirestoreResult<Document> {
         if let Some(parent) = self.parent {
             self.db

src/fluent_api/listing_builder.rs

@@ -45,6 +45,7 @@ where
         }
     }
 
+    /// Select a collection to list documents from
     #[inline]
     pub fn from(self, collection: &str) -> FirestoreListingDocBuilder<'a, D> {
         let params: FirestoreListDocParams = FirestoreListDocParams::new(collection.to_string())
@@ -91,6 +92,7 @@ where
         }
     }
 
+    /// Sets the page size for the query
     #[inline]
     pub fn page_size(self, value: usize) -> Self {
         Self {
@@ -99,6 +101,15 @@ where
         }
     }
 
+    /// Order the querry by the given field
+    ///
+    /// Usage:
+    /// ```
+    /// .order_by([(
+    ///        path!(MyTestStructure::some_id),
+    ///       FirestoreQueryDirection::Ascending,
+    ///   )])
+    /// ```
     #[inline]
     pub fn order_by<I>(self, fields: I) -> Self
     where
@@ -113,6 +124,9 @@ where
         }
     }
 
+    /// Gets the first page of results
+    ///
+    /// Page size can be set with the `page_size`
     pub async fn get_page(self) -> FirestoreResult<FirestoreListDocResult> {
         self.db.list_doc(self.params).await
     }

src/fluent_api/mod.rs

@@ -41,33 +41,47 @@ where
         Self { db }
     }
 
+    /// Select one or more documents from the database
+    ///
+    /// Single documents can be selected by thier IDs, multiple documents can be selected with a query filter.
     #[inline]
     pub fn select(self) -> FirestoreSelectInitialBuilder<'a, D> {
         FirestoreSelectInitialBuilder::new(self.db)
     }
 
+    /// Insert a new document into the database
     #[inline]
     pub fn insert(self) -> FirestoreInsertInitialBuilder<'a, D> {
         FirestoreInsertInitialBuilder::new(self.db)
     }
 
+    /// Update a document in the database
+    ///
+    /// Documents can be implicitly created using update when using your own document IDs. Useful to use in batches and transactions.
     #[inline]
     pub fn update(self) -> FirestoreUpdateInitialBuilder<'a, D> {
         FirestoreUpdateInitialBuilder::new(self.db)
     }
 
+    /// Delete a document in the database
     #[inline]
     pub fn delete(self) -> FirestoreDeleteInitialBuilder<'a, D> {
         FirestoreDeleteInitialBuilder::new(self.db)
     }
 
+    /// List documents in a collection (or subcollection)
+    ///
+    /// This is a convenience method to list all documents in a collection. For more complex queries, use the select method.
     #[inline]
     pub fn list(self) -> FirestoreListingInitialBuilder<'a, D> {
         FirestoreListingInitialBuilder::new(self.db)
     }
 }
 
 impl FirestoreDb {
+    /// Fluent API
+    ///
+    /// The Fluent API simplifies development and the developer experience. The library provides a more high level API starting with v0.12.x. This is the recommended API for all applications to use.
     #[inline]
     pub fn fluent(&self) -> FirestoreExprBuilder<FirestoreDb> {
         FirestoreExprBuilder::new(self)

src/fluent_api/select_builder.rs

@@ -58,6 +58,7 @@ where
         }
     }
 
+    /// Select multiple documents from collection
     #[inline]
     pub fn from<C>(self, collection: C) -> FirestoreSelectDocBuilder<'a, D>
     where
@@ -68,6 +69,7 @@ where
         FirestoreSelectDocBuilder::new(self.db, params)
     }
 
+    /// Select one or more documents by Id
     #[inline]
     pub fn by_id_in(self, collection: &str) -> FirestoreSelectByIdBuilder<'a, D> {
         FirestoreSelectByIdBuilder::new(self.db, collection.to_string(), self.return_only_fields)
@@ -352,6 +354,7 @@ where
         }
     }
 
+    /// Get multiple documents by their ids.
     pub async fn batch<S, I>(
         self,
         document_ids: I,
@@ -408,6 +411,7 @@ where
         }
     }
 
+    /// Select documents to listen for changes with the given ids.
     pub fn batch_listen<S, I>(
         self,
         document_ids: I,
@@ -744,6 +748,8 @@ where
         }
     }
 
+    // Specify the listener
+    // TODO: what does the `FirestoreListenerTarget` do?
     #[inline]
     pub fn add_target<S>(
         self,