[Rust] Add misc documentation

Author: emesare

rust/src/architecture.rs

@@ -123,19 +123,34 @@ pub trait Architecture: 'static + Sized + AsRef<CoreArchitecture> {
 
     fn associated_arch_by_addr(&self, addr: u64) -> CoreArchitecture;
 
+    /// Returns the [`InstructionInfo`] at the given virtual address with `data`.
+    ///
+    /// The [`InstructionInfo`] object should always fill the proper length and branches if not, the
+    /// next instruction will likely be incorrect.
     fn instruction_info(&self, data: &[u8], addr: u64) -> Option<InstructionInfo>;
+
     fn instruction_text(
         &self,
         data: &[u8],
         addr: u64,
     ) -> Option<(usize, Vec<InstructionTextToken>)>;
+
+    // TODO: Why do we need to return a boolean here? Does `None` not represent the same thing?
+    /// Appends arbitrary low-level il instructions to `il`.
+    ///
+    /// If `None` is returned, no instructions were appended and the data is invalid. If `Some` is returned,
+    /// the instructions consumed length is returned (necessary for variable length instruction decoding).
     fn instruction_llil(
         &self,
         data: &[u8],
         addr: u64,
         il: &LowLevelILMutableFunction,
     ) -> Option<(usize, bool)>;
 
+    /// Performs basic block recovery and commits the results to the function analysis.
+    ///
+    /// NOTE: Only implement this method if function-level analysis is required. Otherwise, do not
+    /// implement to let default basic block analysis take place.
     fn analyze_basic_blocks(
         &self,
         function: &mut Function,
@@ -147,7 +162,7 @@ pub trait Architecture: 'static + Sized + AsRef<CoreArchitecture> {
     }
 
     /// Fallback flag value calculation path. This method is invoked when the core is unable to
-    /// recover flag use semantics, and resorts to emitting instructions that explicitly set each
+    /// recover the flag using semantics and resorts to emitting instructions that explicitly set each
     /// observed flag to the value of an expression returned by this function.
     ///
     /// This function *MUST NOT* append instructions that have side effects.
@@ -166,11 +181,10 @@ pub trait Architecture: 'static + Sized + AsRef<CoreArchitecture> {
         Some(get_default_flag_write_llil(self, role, op, il))
     }
 
-    /// Determines what flags need to be examined in order to attempt automatic recovery of the
-    /// semantics of this flag use.
+    /// Determines what flags need to be examined to attempt automatic recovery of the flag uses semantics.
     ///
-    /// If automatic recovery is not possible, the `flag_cond_llil` method will be invoked to give
-    /// this `Architecture` implementation arbitrary control over the expression to be evaluated.
+    /// If automatic recovery is not possible, the [`Architecture::flag_cond_llil`] method will be invoked
+    /// to give this [`Architecture`] implementation arbitrary control over the expression to be evaluated.
     fn flags_required_for_flag_condition(
         &self,
         _condition: FlagCondition,
@@ -485,6 +499,12 @@ impl Architecture for CoreArchitecture {
         }
     }
 
+    /// Performs basic block recovery and commits the results to the function analysis.
+    ///
+    /// NOTE: Only implement this method if function-level analysis is required. Otherwise, do not
+    /// implement to let default basic block analysis take place.
+    ///
+    /// NOTE: The default implementation exists in C++ here: <https://github.com/Vector35/binaryninja-api/blob/dev/defaultabb.cpp>
     fn analyze_basic_blocks(
         &self,
         function: &mut Function,

rust/src/binary_view.rs

@@ -1322,6 +1322,11 @@ pub trait BinaryViewExt: BinaryViewBase {
         }
     }
 
+    /// This list contains the analysis entry function, and functions like init_array, fini_array,
+    /// and TLS callbacks etc.
+    ///
+    /// We see `entry_functions` as good starting points for analysis, these functions normally don't
+    /// have internal references. Exported functions in a dll/so file are not included.
     fn entry_point_functions(&self) -> Array<Function> {
         unsafe {
             let mut count = 0;
@@ -1706,6 +1711,9 @@ pub trait BinaryViewExt: BinaryViewBase {
         }
     }
 
+    /// Retrieve the metadata as the type `T`.
+    ///
+    /// Fails if the metadata does not exist, or if the metadata failed to coerce to type `T`.
     fn get_metadata<T>(&self, key: &str) -> Option<Result<T>>
     where
         T: for<'a> TryFrom<&'a Metadata>,
@@ -2235,6 +2243,9 @@ pub trait BinaryViewExt: BinaryViewBase {
         }
     }
 
+    /// Retrieve the string that falls on a given virtual address.
+    ///
+    /// NOTE: This returns discovered strings and is therefore governed by `analysis.limits.minStringLength` and other settings.
     fn string_at(&self, addr: u64) -> Option<BNStringReference> {
         let mut str_ref = BNStringReference::default();
         let success = unsafe { BNGetStringAtAddress(self.as_ref().handle, addr, &mut str_ref) };

rust/src/lib.rs

@@ -555,7 +555,7 @@ pub fn license_count() -> i32 {
 
 /// Set the license that will be used once the core initializes. You can reset the license by passing `None`.
 ///
-/// If not set the normal license retrieval will occur:
+/// If not set, the normal license retrieval will occur:
 /// 1. Check the BN_LICENSE environment variable
 /// 2. Check the Binary Ninja user directory for license.dat
 #[cfg(not(feature = "demo"))]
@@ -623,14 +623,15 @@ pub fn add_optional_plugin_dependency(name: &str) {
     unsafe { BNAddOptionalPluginDependency(raw_name.as_ptr()) };
 }
 
-// Provide ABI version automatically so that the core can verify binary compatibility
+/// Exported function to tell the core what core ABI version this plugin was compiled against.
 #[cfg(not(feature = "no_exports"))]
 #[no_mangle]
 #[allow(non_snake_case)]
 pub extern "C" fn CorePluginABIVersion() -> u32 {
     plugin_abi_version()
 }
 
+/// Exported function to tell the core what UI ABI version this plugin was compiled against.
 #[cfg(not(feature = "no_exports"))]
 #[no_mangle]
 pub extern "C" fn UIPluginABIVersion() -> u32 {

rust/src/llvm.rs

@@ -1,3 +1,7 @@
+//! LLVM functionality exposed by the core.
+//!
+//! Also see [`crate::demangle::demangle_llvm`].
+
 use binaryninjacore_sys::{
     BNLlvmServicesAssemble, BNLlvmServicesAssembleFree, BNLlvmServicesDisasmInstruction,
     BNLlvmServicesInit,