From 39f183cb5ea8f5514a0010b9b9a43f2d449567cd Mon Sep 17 00:00:00 2001
From: iximeow <me@iximeow.net>
Date: Sun, 2 Jan 2022 00:01:55 -0800
Subject: document the crate

---
 src/lib.rs | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

(limited to 'src/lib.rs')

diff --git a/src/lib.rs b/src/lib.rs
index ad2eb01..58a7667 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,4 +1,52 @@
+//! # `yaxpeax-arm`, a decoder for `arm` instruction sets.
+//!
+//! `yaxpeax-arm` provides `armv7` (and below) decoders, including `thumb` support, as well a
+//! decoder for `armv8`/`a64`.
+//!
+//! ## usage
+//!
+//! `yaxpeax-arm` is currently only usable through `yaxpeax-arch` traits:
+//! ```
+//! mod decoder {
+//!     use yaxpeax_arch::{Arch, AddressDisplay, Decoder, Reader, ReaderBuilder};
+//!
+//!     pub fn decode_stream<
+//!         'data,
+//!         A: yaxpeax_arch::Arch,
+//!         U: ReaderBuilder<A::Address, A::Word>,
+//!     >(data: U) where
+//!         A::Instruction: std::fmt::Display,
+//!     {
+//!         let mut reader = ReaderBuilder::read_from(data);
+//!         let mut address: A::Address = reader.total_offset();
+//!
+//!         let decoder = A::Decoder::default();
+//!         let mut decode_res = decoder.decode(&mut reader);
+//!         loop {
+//!             match decode_res {
+//!                 Ok(ref inst) => {
+//!                     println!("{}: {}", address.show(), inst);
+//!                     decode_res = decoder.decode(&mut reader);
+//!                     address = reader.total_offset();
+//!                 }
+//!                 Err(e) => {
+//!                     println!("{}: decode error: {}", address.show(), e);
+//!                     break;
+//!                 }
+//!             }
+//!         }
+//!     }
+//! }
+//!
+//! use yaxpeax_arm::armv8::a64::Arch;
+//! use yaxpeax_arch::{ReaderBuilder, U8Reader};
+//! let data: &[u8] = &[0x94, 0x02, 0x1e, 0x32];
+//! // would display `orr w20, w20, #0x4`.
+//! decoder::decode_stream::<x86_64, _>(data);
+//! ```
+
 #![no_std]
+#![deny(missing_docs)]
 
 #[cfg(feature="use-serde")]
 #[macro_use] extern crate serde_derive;
@@ -7,5 +55,7 @@ extern crate serde;
 extern crate yaxpeax_arch;
 extern crate bitvec;
 
+/// `yaxpeax-arm`'s `ARMv7` decoder and `Arch` implementation.
 pub mod armv7;
+/// `yaxpeax-arm`'s `ARMv8` decoder and `Arch` implementation.
 pub mod armv8;
-- 
cgit v1.1