add crate-level documentation; add note on installing bindgen

requirements

README.md

@@ -16,6 +16,8 @@ The bindings and examples have been tested against IDA Pro v9.0 on Windows
 In addition to the latest v9.0 IDA SDK and IDA itself, a recent version of
 LLVM/Clang is required (this is to help generate bindings from the SDK), it can
 be obtained from, e.g., [here](https://github.com/llvm/llvm-project/releases).
+See the [bindgen documentation](https://rust-lang.github.io/rust-bindgen/requirements.html)
+for extended instructions for each supported operating system/environment.
 
 ## Developing with idalib
 

idalib/src/lib.rs

@@ -1,3 +1,79 @@
+//! # idalib
+//!
+//! idalib is a Rust library providing idiomatic bindings for the IDA SDK, enabling the development
+//! of standalone analysis tools using IDA v9.0’s idalib.
+//!
+//! ## Usage
+//!
+//! To use idalib, add it as a dependency in your `Cargo.toml` and include a `build.rs` file in
+//! your project to properly link against IDA:
+//!
+//! ```toml
+//! [dependencies]
+//! idalib = "0.4"
+//!
+//! [build-dependencies]
+//! idalib-build = "0.4"
+//! ```
+//!
+//! Here is a basic example of a `build.rs` file:
+//!
+//! ```rust,ignore
+//! fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     idalib_build::configure_linkage()?;
+//!     Ok(())
+//! }
+//! ```
+//!
+//! This script uses the `idalib-build` crate to automatically configure the linkage against IDA.
+//! Ensure that the environment variables `IDASDKDIR` and optionally `IDADIR` are set to point to
+//! your IDA SDK and installation directories, respectively.
+//!
+//! ## Setting Environment Variables
+//!
+//! ### On Linux/macOS
+//!
+//! You can set the environment variables in your terminal session or add them to your shell
+//! configuration file (e.g., `.bashrc`, `.zshrc`):
+//!
+//! ```sh,ignore
+//! export IDASDKDIR=/path/to/ida/sdk
+//! export IDADIR=/path/to/ida/installation
+//! ```
+//!
+//! ### On Windows
+//!
+//! Set environment variables using Command Prompt, PowerShell, or System Properties.
+//!
+//! **Command Prompt:**
+//! ```cmd
+//! set IDASDKDIR=C:\path\to\ida\sdk
+//! set IDADIR=C:\path\to\ida\installation
+//! ```
+//!
+//! **PowerShell:**
+//! ```powershell,ignore
+//! $env:IDASDKDIR = "C:\path\to\ida\sdk"
+//! $env:IDADIR = "C:\path\to\ida\installation"
+//! ```
+//!
+//! **System Properties:**
+//! Go to "Environment Variables" in System Properties and add `IDASDKDIR` and `IDADIR`.
+//!
+//! ## Example
+//!
+//! Here's a simple example of how to use idalib:
+//!
+//! ```rust,ignore
+//! use idalib::idb::IDB;
+//!
+//! fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let idb = IDB::open("/path/to/binary")?;
+//!     // Perform analysis...
+//!     Ok(())
+//! }
+//! ```
+//!
 #![allow(clippy::needless_lifetimes)]
 
 use std::ffi::c_char;