Rust API : Major docs update (still need detailed module and function…

… documentation)

README.md

@@ -11,6 +11,8 @@ Online documentation is available for the following APIs:
 - [C++ API, Stable Branch](https://api.binary.ninja/cpp/)
 - [Python API, Stable Branch](https://api.binary.ninja/)
 - [Python API, Dev Branch](https://dev-api.binary.ninja/)
+- [Rust API, Stable Branch](https://rust.binary.ninja/)
+- [Rust API, Dev Branch](https://rust-dev.binary.ninja/)
 
 ## Branches
 

rust/README.md

@@ -9,9 +9,9 @@
 
 ## Dependencies
 
-Having BinaryNinja installed (and your license registered)
-Clang
-Rust
+Having BinaryNinja installed (and your license registered)  
+Clang  
+Rust  
 
 
 ## How to use
@@ -40,9 +40,9 @@ See the `./examples/`.  Plugin registration commands are in `binaryninja::comman
 binaryninja = { git = "https://github.com/Vector35/binaryninja-api.git", branch = "dev"}
 ```
 
-All standalone binaries should call both `binaryninja::headless::init()` and `binaryninja::headless::shutdown()`.
-All standalone binaries need to provide a `build.rs`.
-See [`examples/template`](examples/template) for details.
+All standalone binaries should call both `binaryninja::headless::init()` and `binaryninja::headless::shutdown()`.  
+All standalone binaries need to provide a `build.rs`.  
+See [`examples/template`](examples/template) for details.  
 
 ---
 

rust/build.rs

@@ -1,4 +1,7 @@
 fn main() {
+    // TODO : Enable the following when https://github.com/rust-lang/rust/issues/43781 stabilizes
+    // #[cfg(doc)]
+    let _ = std::fs::create_dir("target");
     let _ = std::fs::create_dir("target/doc");
     let _ = std::fs::copy("../docs/img/favicon.ico", "target/doc/favicon.ico");
     let _ = std::fs::copy(

rust/examples/template/README.md

@@ -1,8 +1,8 @@
 # Template
 
-[The only official method of providing linker arguments to a crate is through that crate's `build.rs`](https://github.com/rust-lang/cargo/issues/9554), thus this template.
+[The only official method of providing linker arguments to a crate is through that crate's `build.rs`](https://github.com/rust-lang/cargo/issues/9554), thus this template.  
 
-Please see `Cargo.toml` for further configuration options.
+Please see `Cargo.toml` for further configuration options.  
 
 ## Plugins
 
@@ -15,5 +15,5 @@ in `Cargo.toml`.
 
 ## Standalone executables
 
-All standalone executables should call both `binaryninja::headless::init()` and `binaryninja::headless::shutdown()` (see [`src/main.rs`](src/main.rs)).
-Standalone executables will fail to link if you do not provide a `build.rs`.  The one provided here should work.
+All standalone executables should call both `binaryninja::headless::init()` and `binaryninja::headless::shutdown()` (see [`src/main.rs`](src/main.rs)).  
+Standalone executables will fail to link if you do not provide a `build.rs`.  The one provided here should work.  

rust/src/architecture.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Architectures provide disassembly, lifting, and associated metadata about a CPU to inform analysis and decompilation.
+
 // container abstraction to avoid Vec<> (want CoreArchFlagList, CoreArchRegList)
 // RegisterInfo purge
 use binaryninjacore_sys::*;

rust/src/backgroundtask.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Background tasks provide plugins the ability to run tasks in the background so they don't hand the UI
+
 use binaryninjacore_sys::*;
 
 use std::result;

rust/src/basicblock.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+
+
 use std::fmt;
 
 use crate::architecture::CoreArchitecture;

rust/src/binaryreader.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! A convenience class for reading binary data
+
 use binaryninjacore_sys::*;
 
 use crate::binaryview::BinaryView;

rust/src/binaryview.rs

@@ -12,6 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! A view on binary data and queryable interface of a binary file.
+//!
+//! One key job of BinaryView is file format parsing which allows Binary Ninja to read, write, insert, remove portions of the file given a virtual address. For the purposes of this documentation we define a virtual address as the memory address that the various pieces of the physical file will be loaded at.
+//! TODO : Mirror the Python docs for this
+
 use binaryninjacore_sys::*;
 
 pub use binaryninjacore_sys::BNModificationStatus as ModificationStatus;

rust/src/binarywriter.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! A convenience class for writing binary data
+
 use binaryninjacore_sys::*;
 
 use crate::binaryview::BinaryView;

rust/src/callingconvention.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Contains and provides information about different systems' calling conventions to analysis.
+
 use std::borrow::Borrow;
 use std::marker::PhantomData;
 use std::mem;

rust/src/command.rs

@@ -12,6 +12,22 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Provides commands for registering plugins and plugin actions.
+//!
+//! All plugins need to provide one of the following functions for Binary Ninja to call:
+//!
+//! ```rust
+//! pub extern "C" fn CorePluginInit() -> bool {}
+//! ```
+//!
+//! ```rust
+//! pub extern "C" fn UIPluginInit() -> bool {}
+//! ```
+//!
+//! Both of these functions can call any of the following registration functions, though `CorePluginInit` is called during Binary Ninja core initialization, and `UIPluginInit` is called during Binary Ninja UI initialization.
+//!
+//! The return value of these functions should indicate whether they successfully initialized themselves.
+
 use binaryninjacore_sys::{
     BNBinaryView, BNFunction, BNRegisterPluginCommand, BNRegisterPluginCommandForAddress,
     BNRegisterPluginCommandForFunction, BNRegisterPluginCommandForRange,
@@ -24,6 +40,7 @@ use crate::binaryview::BinaryView;
 use crate::function::Function;
 use crate::string::BnStrCompatible;
 
+/// The trait required for generic commands.  See [register] for example usage.
 pub trait Command: 'static + Sync {
     fn action(&self, view: &BinaryView);
     fn valid(&self, view: &BinaryView) -> bool;
@@ -42,6 +59,33 @@ where
     }
 }
 
+/// The function call required for generic commands; commands added in this way will be in the `Plugins` submenu of the menu bar.
+///
+/// # Example
+/// ```rust
+/// Struct MyCommand;
+///
+/// impl Command for MyCommand {
+///     fn action(&self, view: &BinaryView) {
+///         // Your code here
+///     }
+///
+///     fn valid(&self, view: &BinaryView) -> bool {
+///         // Your code here
+///         true
+///     }
+/// }
+///
+/// #[no_mangle]
+/// pub extern "C" fn CorePluginInit() -> bool {
+///     register(
+///         "My Plugin Command",
+///         "A description of my command",
+///         MyCommand {},
+///     );
+///     true
+/// }
+/// ```
 pub fn register<S, C>(name: S, desc: S, command: C)
 where
     S: BnStrCompatible,
@@ -94,6 +138,7 @@ where
     }
 }
 
+/// The trait required for address-associated commands.  See [register_for_address] for example usage.
 pub trait AddressCommand: 'static + Sync {
     fn action(&self, view: &BinaryView, addr: u64);
     fn valid(&self, view: &BinaryView, addr: u64) -> bool;
@@ -112,6 +157,33 @@ where
     }
 }
 
+/// The function call required for generic commands; commands added in this way will be in the `Plugins` submenu of the menu bar.
+///
+/// # Example
+/// ```rust
+/// Struct MyCommand;
+///
+/// impl AddressCommand for MyCommand {
+///     fn action(&self, view: &BinaryView, addr: u64) {
+///         // Your code here
+///     }
+///
+///     fn valid(&self, view: &BinaryView, addr: u64) -> bool {
+///         // Your code here
+///         true
+///     }
+/// }
+///
+/// #[no_mangle]
+/// pub extern "C" fn CorePluginInit() -> bool {
+///     register_for_address(
+///         "My Plugin Command",
+///         "A description of my command",
+///         MyCommand {},
+///     );
+///     true
+/// }
+/// ```
 pub fn register_for_address<S, C>(name: S, desc: S, command: C)
 where
     S: BnStrCompatible,
@@ -164,6 +236,7 @@ where
     }
 }
 
+/// The trait required for range-associated commands.  See [register_for_range] for example usage.
 pub trait RangeCommand: 'static + Sync {
     fn action(&self, view: &BinaryView, range: Range<u64>);
     fn valid(&self, view: &BinaryView, range: Range<u64>) -> bool;
@@ -182,6 +255,33 @@ where
     }
 }
 
+/// The function call required for generic commands; commands added in this way will be in the `Plugins` submenu of the menu bar.
+///
+/// # Example
+/// ```rust
+/// Struct MyCommand;
+///
+/// impl AddressCommand for MyCommand {
+///     fn action(&self, view: &BinaryView, range: Range<u64>) {
+///         // Your code here
+///     }
+///
+///     fn valid(&self, view: &BinaryView, range: Range<u64>) -> bool {
+///         // Your code here
+///         true
+///     }
+/// }
+///
+/// #[no_mangle]
+/// pub extern "C" fn CorePluginInit() -> bool {
+///     register_for_range(
+///         "My Plugin Command",
+///         "A description of my command",
+///         MyCommand {},
+///     );
+///     true
+/// }
+/// ```
 pub fn register_for_range<S, C>(name: S, desc: S, command: C)
 where
     S: BnStrCompatible,
@@ -239,6 +339,7 @@ where
     }
 }
 
+/// The trait required for function-associated commands.  See [register_for_function] for example usage.
 pub trait FunctionCommand: 'static + Sync {
     fn action(&self, view: &BinaryView, func: &Function);
     fn valid(&self, view: &BinaryView, func: &Function) -> bool;
@@ -257,6 +358,33 @@ where
     }
 }
 
+/// The function call required for generic commands; commands added in this way will be in the `Plugins` submenu of the menu bar.
+///
+/// # Example
+/// ```rust
+/// Struct MyCommand;
+///
+/// impl AddressCommand for MyCommand {
+///     fn action(&self, view: &BinaryView, func: &Function) {
+///         // Your code here
+///     }
+///
+///     fn valid(&self, view: &BinaryView, func: &Function) -> bool {
+///         // Your code here
+///         true
+///     }
+/// }
+///
+/// #[no_mangle]
+/// pub extern "C" fn CorePluginInit() -> bool {
+///     register_for_function(
+///         "My Plugin Command",
+///         "A description of my command",
+///         MyCommand {},
+///     );
+///     true
+/// }
+/// ```
 pub fn register_for_function<S, C>(name: S, desc: S, command: C)
 where
     S: BnStrCompatible,

rust/src/custombinaryview.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! An interface for providing your own [BinaryView]s to Binary Ninja.
+
 use binaryninjacore_sys::*;
 
 pub use binaryninjacore_sys::BNModificationStatus as ModificationStatus;

rust/src/databuffer.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! A basic wrapper around an array of binary data
+
 use binaryninjacore_sys::*;
 
 use std::ptr;

rust/src/demangle.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Interfaces for demangling and simplifying mangled names in binaries.
+
 use binaryninjacore_sys::*;
 use std::{ffi::CStr, result};
 

rust/src/flowgraph.rs

@@ -12,6 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Interfaces for creating and displaying pretty CFGs in Binary Ninja.
+
 use binaryninjacore_sys::*;
 
 use crate::disassembly::DisassemblyTextLine;