document the new InstructionAlias bits0.3.3

3 files changed, 34 insertions, 1 deletions

diff --git a/CHANGELOG b/CHANGELOG
index 8cde9b8..23cf31e 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -13,6 +13,19 @@ TODO: impls of `fn one` and `fn zero` so downstream users don't have to import n
 TODO: 0.4.0 or later:
   * remove `mod colors`, crossterm dependency, related feature flags
 
+## 0.3.3
+
+* add `trait InstructionAlias`, for architectures to declare a relationship
+  between "baseline" instructions and the "human-friendly" assembly-level
+  aliases that architectures may have.
+* add `trait ArchDisplayRules`, to try generalizing the more flexible
+  instruction formatting support in some decoders. additionally,
+  `AbsoluteAddressFormatter` has a generic implementation of
+  `ArchDisplayRules` to allow decoded instructions to be printed
+  as if at a certain address in a program, rather than the
+  typical yaxpeax behavior of formatting instructions in an
+  address-independent manner.
+
 ## 0.3.2
 
 fix yaxpeax-arch not building for non-x86 targets when alloc is not enabled
diff --git a/Cargo.toml b/Cargo.toml
index ca47d5b..1db5571 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -7,7 +7,7 @@ keywords = ["disassembly", "disassembler"]
 license = "0BSD"
 name = "yaxpeax-arch"
 repository = "https://git.iximeow.net/yaxpeax-arch/"
-version = "0.3.2"
+version = "0.3.3"
 
 [dependencies]
 "num-traits" = { version = "0.2", default-features = false }
diff --git a/src/lib.rs b/src/lib.rs
index 856e9cc..8707d39 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -237,6 +237,26 @@ pub trait Instruction {
     fn well_defined(&self) -> bool;
 }
 
+/// glue to associate an `Instruction` type with some form of manual- (or convention-)defined
+/// alias.
+///
+/// this primarily exists to give a standard mechanism to convert between the `Instruction`
+/// provided by an `Arch`'s instruction decoder, and some higher-level representation. the
+/// translation to and from an alias ought to round-trip; implementations can assume
+/// `assert_eq!(FooAlias::compute_alias(i).dealias, i)`.
+///
+/// an alias of an [`Instruction`] is, concretely, a (probably!) distinct struct that has *some*
+/// reversible relationship with an instruction. the alias's `Opcode` equivalent is probably a
+/// collection of "new" variants as well as a variant describing "non-aliasing" that simply
+/// contains the architecture's `Opcode`. operands are less likely to structurally vary, but an
+/// instruction's alias may have *different* operands than its original form. as an example,
+/// `xor r1, r1, r1` may be defined to alias as `mov r1, 0` with both a different number of
+/// operands and some variants having different type.
+///
+/// it is also possible that one architecture has more than one kind of alias. the distinct alias
+/// types could, for example, describe different vendors' aliasing rules, conventional rules in
+/// contrast to manual-defined rules, different aliasing rulse for different versions of a manual,
+/// etc. `InstructionAlias` implementations should describe the documentation which they represent.
 pub trait InstructionAlias<I: Instruction>: LengthedInstruction {
     fn compute_alias(t: &I) -> Self;
     fn dealias(&self) -> I;