Better documentation

Author: Nao-ris

src/blob.rs

@@ -31,7 +31,7 @@ use crate::{
 use std::ffi::c_void;
 use std::marker::PhantomData;
 
-/** A binary attachment to a Document. */
+/// A binary attachment to a Document
 pub struct Blob {
     pub(crate) cbl_ref: *const CBLBlob,
 }
@@ -46,7 +46,7 @@ impl CblRef for Blob {
 impl Blob {
     //////// CREATION
 
-    /** Creates a new blob, given its contents as a byte array. */
+    /// Creates a new blob, given its contents as a byte array.
     pub fn new_from_data(data: &[u8], content_type: &str) -> Self {
         unsafe {
             let blob = CBLBlob_CreateWithData(
@@ -57,8 +57,8 @@ impl Blob {
         }
     }
 
-    /** Creates a new blob from data that has has been written to a [`Writer`].
-    You should then add the blob to a document as a property, using [`Slot::put_blob`]. */
+    /// Creates a new blob from data that has has been written to a [`Writer`].
+    /// You should then add the blob to a document as a property, using [`Slot::put_blob`].
     pub fn new_from_stream(mut stream: BlobWriter, content_type: &str) -> Self {
         unsafe {
             let blob = CBLBlob_CreateWithStream(from_str(content_type).get_ref(), stream.get_ref());
@@ -67,7 +67,7 @@ impl Blob {
         }
     }
 
-    // called by FleeceReference::as_blob()
+    /// called by FleeceReference::as_blob()
     pub(crate) fn from_value<V: FleeceReference>(value: &V) -> Option<Self> {
         unsafe {
             let blob = FLDict_GetBlob(FLValue_AsDict(value._fleece_ref()));
@@ -81,30 +81,30 @@ impl Blob {
 
     //////// ACCESSORS
 
-    /** The length of the content data in bytes. */
+    /// The length of the content data in bytes
     pub fn length(&self) -> u64 {
         unsafe { CBLBlob_Length(self.get_ref()) }
     }
 
-    /** The unique digest of the blob: A base64-encoded SHA-1 digest of its data. */
+    /// The unique digest of the blob: A base64-encoded SHA-1 digest of its data
     pub fn digest(&self) -> &str {
         unsafe { CBLBlob_Digest(self.get_ref()).as_str().unwrap() }
     }
 
-    /** The MIME type assigned to the blob, if any. */
+    /// The MIME type assigned to the blob, if any
     pub fn content_type(&self) -> Option<&str> {
         unsafe { CBLBlob_ContentType(self.get_ref()).as_str() }
     }
 
-    /** The blob's metadata properties as a dictionary. */
+    /// The blob's metadata properties as a dictionary
     pub fn properties(&self) -> Dict {
         unsafe { Dict::new(CBLBlob_Properties(self.get_ref())) }
     }
 
     //////// READING:
 
-    /** Reads the blob's contents into memory and returns them as a byte array.
-    This can potentially allocate a lot of memory! */
+    /// Reads the blob's contents into memory and returns them as a byte array.
+    /// This can potentially allocate a lot of memory!
     pub fn load_content(&self) -> Result<Vec<u8>> {
         unsafe {
             let mut err = CBLError::default();
@@ -113,7 +113,7 @@ impl Blob {
         }
     }
 
-    /** Opens a stream for reading a blob's content from disk. */
+    /// Opens a stream for reading a blob's content from disk.
     pub fn open_content(&self) -> Result<BlobReader> {
         check_ptr(
             |err| unsafe { CBLBlob_OpenContentStream(self.get_ref(), err) },
@@ -146,15 +146,15 @@ impl Clone for Blob {
 //////// BLOB ADDITIONS FOR ARRAY / DICT:
 
 impl Slot<'_> {
-    /** Stores a Blob reference in an Array or Dict. This is how you add a Blob to a Document. */
+    /// Stores a Blob reference in an Array or Dict. This is how you add a Blob to a Document.
     pub fn put_blob(self, blob: &mut Blob) {
         unsafe { FLSlot_SetBlob(self.get_ref(), blob.get_ref() as *mut CBLBlob) }
     }
 }
 
 //////// BLOB READER
 
-/** A stream for reading Blob conents. */
+/// A stream for reading Blob conents
 pub struct BlobReader<'r> {
     pub blob: &'r Blob,
     stream_ref: *mut CBLBlobReadStream,
@@ -192,9 +192,8 @@ impl Drop for BlobReader<'_> {
 
 //////// BLOB WRITER
 
-/** A stream for writing data that will become a Blob's contents.
-After you're done writing the data, call [`Blob::new_from_stream`],
-then add the Blob to a document property via [`Slot::put_blob`]. */
+/// A stream for writing data that will become a Blob's contents.
+/// After you're done writing the data, call [`Blob::new_from_stream`], then add the Blob to a document property via [`Slot::put_blob`].
 pub struct BlobWriter<'d> {
     stream_ref: *mut CBLBlobWriteStream,
     db: PhantomData<&'d mut Database>,

src/collection.rs

@@ -10,24 +10,67 @@ use crate::{
 
 pub static DEFAULT_NAME: &str = "_default";
 
+/// A Collection represents a collection which is a container for documents.
+///
+/// A collection can be thought as a table in a relational database. Each collection belongs to
+/// a scope which is simply a namespce, and has a name which is unique within its scope.
+///
+/// When a new database is created, a default collection named "_default" will be automatically
+/// created. The default collection is created under the default scope named "_default".
+/// The name of the default collection and scope can be referenced by using
+/// kCBLDefaultCollectionName and \ref kCBLDefaultScopeName constant.
+///
+///    @note The default collection cannot be deleted.
+///
+///    When creating a new collection, the collection name, and the scope name are required.
+///    The naming rules of the collections and scopes are as follows:
+///    - Must be between 1 and 251 characters in length.
+///    - Can only contain the characters A-Z, a-z, 0-9, and the symbols _, -, and %.
+///    - Cannot start with _ or %.
+///    - Both scope and collection names are case sensitive.
+///
+///    ## `CBLCollection` Lifespan
+///    `CBLCollection` is ref-counted. Same as the CBLDocument, the CBLCollection objects
+///    created or retrieved from the database must be released after you are done using them.
+///    When the database is closed or released, the collection objects will become invalid,
+///    most operations on the invalid \ref CBLCollection object will fail with either the
+///    \ref kCBLErrorNotOpen error or null/zero/empty result.
+///
+///    ##Legacy Database and API
+///    When using the legacy database, the existing documents and indexes in the database will be
+///    automatically migrated to the default collection.
+///
+///    Any pre-existing database functions that refer to documents, listeners, and indexes without
+///    specifying a collection such as \ref CBLDatabase_GetDocument will implicitly operate on
+///    the default collection. In other words, they behave exactly the way they used to, but
+///    collection-aware code should avoid them and use the new Collection API instead.
+///    These legacy functions are deprecated and will be removed eventually.
 #[derive(Debug, PartialEq, Eq)]
 pub struct Collection {
     cbl_ref: *mut CBLCollection,
 }
 
 impl Collection {
+    pub const DEFAULT_NAME: &str = "_default";
+    pub const DEFAULT_FULLE_NAME: &str = "_default._default";
+
+    //////// CONSTRUCTORS:
+
+    /// Takes ownership of the object and increase it's reference counter.
     pub(crate) fn retain(cbl_ref: *mut CBLCollection) -> Self {
         Self {
             cbl_ref: unsafe { retain(cbl_ref) },
         }
     }
 
-    /** Returns the scope of the collection. */
+    ////////
+
+    /// Returns the scope of the collection.
     pub fn scope(&self) -> Scope {
         unsafe { Scope::retain(CBLCollection_Scope(self.get_ref())) }
     }
 
-    /** Returns the collection name. */
+    /// Returns the collection name.
     pub fn name(&self) -> String {
         unsafe {
             CBLCollection_Name(self.get_ref())
@@ -36,7 +79,7 @@ impl Collection {
         }
     }
 
-    /** Returns the collection full name */
+    /// Returns the collection full name.
     pub fn full_name(&self) -> String {
         unsafe {
             CBLCollection_FullName(self.get_ref())
@@ -45,17 +88,17 @@ impl Collection {
         }
     }
 
-    /** Returns the collection's database */
+    /// Returns the collection's database.
     pub fn database(&self) -> Database {
         unsafe { Database::wrap(CBLCollection_Database(self.get_ref())) }
     }
 
-    /** Returns the number of documents in the collection. */
+    /// Returns the number of documents in the collection.
     pub fn count(&self) -> u64 {
         unsafe { CBLCollection_Count(self.get_ref()) }
     }
 
-    /** Registers a collection change listener callback. It will be called after one or more documents are changed on disk. */
+    /// Registers a collection change listener callback. It will be called after one or more documents are changed on disk.
     pub fn add_listener(
         &mut self,
         listener: CollectionChangeListener,
@@ -97,8 +140,8 @@ impl Clone for Collection {
     }
 }
 
-/** A collection change listener callback, invoked after one or more documents are changed on disk. */
-type CollectionChangeListener = Box<dyn Fn(Collection, Vec<String>)>;
+/// A collection change listener callback, invoked after one or more documents are changed on disk.
+pub type CollectionChangeListener = Box<dyn Fn(Collection, Vec<String>)>;
 
 #[no_mangle]
 unsafe extern "C" fn c_collection_change_listener(