[Rust] Misc docs

Author: emesare

rust/src/background_task.rs

@@ -70,6 +70,9 @@ impl BackgroundTask {
         Self { handle }
     }
 
+    /// Begin the [`BackgroundTask`], you must manually finish the task by calling [`BackgroundTask::finish`].
+    ///
+    /// If you wish to automatically finish the task when leaving the scope, use [`BackgroundTask::enter`].
     pub fn new(initial_text: &str, can_cancel: bool) -> Ref<Self> {
         let text = initial_text.to_cstr();
         let handle = unsafe { BNBeginBackgroundTask(text.as_ptr(), can_cancel) };

rust/src/database.rs

@@ -30,7 +30,7 @@ impl Database {
         Ref::new(Self { handle })
     }
 
-    /// Get a snapshot by its id, or None if no snapshot with that id exists
+    /// Get a [`Snapshot`] by its `id`, or `None` if no snapshot with that `id` exists.
     pub fn snapshot_by_id(&self, id: SnapshotId) -> Option<Ref<Snapshot>> {
         let result = unsafe { BNGetDatabaseSnapshot(self.handle.as_ptr(), id.0) };
         NonNull::new(result).map(|handle| unsafe { Snapshot::ref_from_raw(handle) })
@@ -113,8 +113,9 @@ impl Database {
         SnapshotId(new_id)
     }
 
-    /// Trim a snapshot's contents in the database by id, but leave the parent/child
-    /// hierarchy intact. Future references to this snapshot will return False for has_contents
+    /// Trim a snapshot's contents in the database but leave the parent/child hierarchy intact.
+    ///
+    /// NOTE: Future references to this snapshot will return `false` for [`Database::snapshot_has_data`]
     pub fn trim_snapshot(&self, id: SnapshotId) -> Result<(), ()> {
         if unsafe { BNTrimDatabaseSnapshot(self.handle.as_ptr(), id.0) } {
             Ok(())
@@ -193,6 +194,7 @@ impl Database {
         unsafe { KeyValueStore::ref_from_raw(NonNull::new(result).unwrap()) }
     }
 
+    /// Closes then reopens the database.
     pub fn reload_connection(&self) {
         unsafe { BNDatabaseReloadConnection(self.handle.as_ptr()) }
     }

rust/src/file_metadata.rs

@@ -583,7 +583,8 @@ impl FileMetadata {
 
     /// Get the database attached to this file.
     ///
-    /// Only available if this file is a database, or has called [`FileMetadata::create_database`].
+    /// Only available if this file is a database, or [`FileMetadata::create_database`] has previously
+    /// been called on this file.
     pub fn database(&self) -> Option<Ref<Database>> {
         let result = unsafe { BNGetFileMetadataDatabase(self.handle) };
         NonNull::new(result).map(|handle| unsafe { Database::ref_from_raw(handle) })

rust/src/platform.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Contains all information related to the execution environment of the binary, mainly the calling conventions used
+//! A [`Platform`] models the information related to the execution environment of the binary.
 
 use crate::{
     architecture::{Architecture, CoreArchitecture},
@@ -29,6 +29,8 @@ use std::fmt::Debug;
 use std::ptr::NonNull;
 use std::{borrow::Borrow, ffi, ptr};
 
+/// A platform describes the target [`CoreArchitecture`] and platform-specific information such as
+/// the calling conventions and generic types (think `HRESULT` on Windows).
 #[derive(PartialEq, Eq, Hash)]
 pub struct Platform {
     pub(crate) handle: *mut BNPlatform,