fix doc items, add example for use of yaxpeax_x86 by yaxpeax_arch traits1.0.3

4 files changed, 51 insertions, 7 deletions

diff --git a/CHANGELOG b/CHANGELOG
index d7461cb..5ae5dba 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,7 @@
+## 1.0.3
+
+* fix a few broken doc links, added example of yaxpeax-x86 usage through yaxpeax-arch traits
+
 ## 1.0.2
 * remove a stale line from README
 
diff --git a/Cargo.toml b/Cargo.toml
index f3150a8..86cbe2b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 
 name = "yaxpeax-x86"
-version = "1.0.2"
+version = "1.0.3"
 authors = [ "iximeow <me@iximeow.net>" ]
 license = "0BSD"
 repository = "http://git.iximeow.net/yaxpeax-x86/"
@@ -10,7 +10,7 @@ readme = "README.md"
 edition = "2018"
 
 [dependencies]
-yaxpeax-arch = { version = "0.2.0", default-features = false, features = [] }
+yaxpeax-arch = { version = "0.2.2", default-features = false, features = [] }
 "num-traits" = { version = "0.2", default-features = false }
 "serde" = { version = "1.0", optional = true }
 "serde_json" = { version = "1.0", optional = true }
diff --git a/README.md b/README.md
index 21d7769..bdda414 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
 
 x86 decoders implemented as part of the yaxpeax project, implementing traits provided by `yaxpeax-arch`.
 
-Rust users of this library will either want to use the [quick and dirty APIs], or more generic decode interfaces from `yaxpeax-arch` - appropriate when mixing `yaxpeax-x86` usage with other `yaxpeax` decoders, such as `yaxpeax-arm`. examples of both styles are provided [in the documentation](https://docs.rs/yaxpeax-x86/).
+Rust users of this library will either want to use the [quick and dirty APIs](https://docs.rs/yaxpeax-x86/latest/yaxpeax_x86/long_mode/struct.InstDecoder.html#method.decode_slice), or more [generic decode interfaces](https://docs.rs/yaxpeax-arch/latest/yaxpeax_arch/trait.Decoder.html#method.decode) from `yaxpeax-arch` - appropriate when mixing `yaxpeax-x86` usage with other `yaxpeax` decoders, such as `yaxpeax-arm`. examples of both styles are provided [in the documentation](https://docs.rs/yaxpeax-x86/).
 
 the `ffi/` directory provides a repackaging of `yaxpeax-x86` suitable for use by non-Rust callers, such as C or C++. see the `examples` directory for FFI usage of this library.
 
@@ -17,7 +17,7 @@ the `ffi/` directory provides a repackaging of `yaxpeax-x86` suitable for use by
 * pretty small?
 
 ### `#[no_std]`
-the decoders provided by `yaxpeax-x86` are designed to be usable in a `no_std` setting, and does so by default. to build `yaxpeax_x86` without `std`, add the parameter `default-features = false` to your `yaxpeax-x86` dependency; the [ffi packaging] of `yaxpeax_x86` does this and builds without the Rust standard library as well. serde can be enabled without `std`, but json serialization/deserialization [need some careful attention](https://serde.rs/no-std.html) in that mode. as well as the `colors` feature to render instructions with default (eg terminal-friendly) syntax highlighting.
+the decoders provided by `yaxpeax-x86` are designed to be usable in a `no_std` setting, and does so by default. to build `yaxpeax_x86` without `std`, add the parameter `default-features = false` to your `yaxpeax-x86` dependency; the [ffi packaging](https://git.iximeow.net/yaxpeax-x86/tree/ffi) of `yaxpeax_x86` does this and builds without the Rust standard library as well. serde can be enabled without `std`, but json serialization/deserialization [need some careful attention](https://serde.rs/no-std.html) in that mode. as well as the `colors` feature to render instructions with default (eg terminal-friendly) syntax highlighting.
 
 ### instruction set extensions
 `yaxpeax-x86` decoders provide the option to specify what [instruction set extensions](http://git.iximeow.net/yaxpeax-x86/tree/src/long_mode/mod.rs#n1297) are eligible when decoding, to support decoding x86 instructions as understood by a particular microarchitecture. the default impls of decoders in `yaxpeax_x86` take an optimistsic approach to decoding and assumes all feature sets are available, as well as accepting both intel-specific and amd-specific quirks around undefined encodings.
diff --git a/src/lib.rs b/src/lib.rs
index 2bee840..84353ba 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -17,9 +17,9 @@
 //!
 //! instructions, operands, registers, and generally all decoding structures, are in their mode's
 //! repsective submodule:
-//! * `x86_64`/`amd64` decoding is under [`yaxpeax_x86::long_mode`]
-//! * `x86_32`/`x86` decoding is under [`yaxpeax_x86::protected_mode`]
-//! * `x86_16`/`8086` decoding is under [`yaxpeax_x86::real_mode`]
+//! * `x86_64`/`amd64` decoding is under [`long_mode`]
+//! * `x86_32`/`x86` decoding is under [`protected_mode`]
+//! * `x86_16`/`8086` decoding is under [`real_mode`]
 //!
 //! all modes have equivalent data available in a decoded instruction. for example, all modes have
 //! library-friendly `Operand` and `RegSpec` types:
@@ -48,6 +48,46 @@
 //! assert_eq!("dword", mem_size.to_string());
 //! ```
 //!
+//! `yaxpeax-x86` can also be used to decode instructions generically through the `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_x86::amd64::{Arch as x86_64};
+//! use yaxpeax_arch::{ReaderBuilder, U8Reader};
+//! let data: &[u8] = &[0x55, 0x33, 0xc0, 0x48, 0x8b, 0x02, 0x5d, 0xc3];
+//! decoder::decode_stream::<x86_64, _>(data);
+//! ```
+//!
 //! ## `#![no_std]`
 //!
 //! `yaxpeax-x86` supports `no_std` usage. to be built `no_std`, `yaxpeax-x86` only needs