add better BNIL API documentation examples

5 files changed, 31 insertions, 4 deletions

diff --git a/docs/dev/bnil-llil.md b/docs/dev/bnil-llil.md
index ca3a8379..2a339371 100644
--- a/docs/dev/bnil-llil.md
+++ b/docs/dev/bnil-llil.md
@@ -1,4 +1,4 @@
-# Binary Ninja Intermediate Language Series, Part 1: Low Level IL
+# Binary Ninja Intermediate Language: Low Level IL
 
 Make sure to checkout the [BNIL overview](bnil-overview.md) first if you haven't already. Or feel free to skip to [part 2](bnil-mlil.md) which covers MLIL. This developer guide is intended to cover some of the mechanics of the LLIL to distinguish it from the other ILs in the BNIL family.
 
@@ -312,4 +312,4 @@ The rest of the instructions are pretty much self-explanatory to anyone with fam
 * `LLIL_FLAG_BIT_SSA ` - 
 * `LLIL_FLAG_PHI ` - 
 * `LLIL_FLAG_SSA ` - 
-* `LLIL_TAILCALL_SSA ` - 
\ No newline at end of file
+* `LLIL_TAILCALL_SSA ` - 
diff --git a/docs/dev/bnil-mlil.md b/docs/dev/bnil-mlil.md
index 643e7ce6..dadd0d01 100644
--- a/docs/dev/bnil-mlil.md
+++ b/docs/dev/bnil-mlil.md
@@ -1,4 +1,5 @@
 # Binary Ninja Intermediate Language Series, Part 2: Medium Level IL
+# Binary Ninja Intermediate Language: Medium Level IL
 
 The Medium Level Intermediate Language (MLIL) is the second major representation in the Binary Ninja Intermediate Language (BNIL) family of intermediate languages. Much like [LLIL](./bnil-llil.md) this representation is tree based and has many of the same instructions. This representation is distinct in a few key ways.
 
diff --git a/docs/dev/bnil-overview.md b/docs/dev/bnil-overview.md
index a6b367fe..dcddc686 100644
--- a/docs/dev/bnil-overview.md
+++ b/docs/dev/bnil-overview.md
@@ -1,4 +1,4 @@
-# Binary Ninja Intermediate Language Series, Part 0: Overview
+# Binary Ninja Intermediate Language: Overview
 
 The Binary Ninja Intermediate Language (BNIL) is a semantic representation of the assembly language instructions for a native architecture in Binary Ninja.  BNIL is actually a family of intermediate languages that work together to provide functionality at different abstraction layers. 
 
@@ -78,6 +78,32 @@ Offsets into variables are specified with a `:$offset` syntax indicating how man
 
 So putting all that together, if you were to see the following in an IL expression:
 
-```sx.q(rax_2:0.d)```
+```
+sx.q(rax_2:0.d)
+```
 
 It represents the lower 32-bits of variable `rax_2`, sign-extended into a 64-bit variable.
+
+## Using the API with ILs
+
+When you want to use the API to access BNIL instructions, here are a few tips that will help you with the task. First, if you want to learn what properties different instructions have, instead of manually using `dir()` or looking in the documentation ([1](https://docs.binary.ninja/dev/bnil-llil.html#the-instructions), [2](https://docs.binary.ninja/dev/bnil-mlil.html#the-instruction-set)) lists is to use the [BNIL Graph](https://github.com/Vector35/community-plugins#:~:text=BNIL%20Instruction%20Graph) plugin. Another very useful plugin is the [IL Hierarch](https://github.com/Vector35/community-plugins#:~:text=into%20Binary%20Ninja.-,ilhierarchy,-Fabian%20Freyer) plugin. This plugin is extremely useful for showing the _structure_ of IL instructions relative to one another. You can use several APIS ([1](https://api.binary.ninja/binaryninja.lowlevelil-module.html#binaryninja.lowlevelil.LowLevelILInstruction.show_llil_hierarchy), [2](https://api.binary.ninja/binaryninja.mediumlevelil-module.html#binaryninja.mediumlevelil.MediumLevelILInstruction.show_mlil_hierarchy), [3](https://api.binary.ninja/binaryninja.highlevelil-module.html#binaryninja.highlevelil.HighLevelILInstruction.show_hlil_hierarchy)) to see this overall structure, but the IL Hierarchy plugin lets you select a single IL instructions and see visually which categories of IL instructions it are in. 
+
+![LLIL Hierarchy](../img/llil-hierarchy.png)
+
+So for example, if you want to try to determine whether a given instruction is a Call (which includes syscalls) you can use:
+
+```
+for h in current_hlil.instructions:
+    if isinstance(h, Call):
+        print(f"{str(h)} is a Call of some sort")
+    if isinstance(h, LocalCall):
+        print(f"{str(h)} is a LocalCall which means no syscalls! It has {len(h.params)} parameters.")
+```
+
+Here's what that instruction might look like when selected with the IL Hierarchy plugin:
+
+![HLIL Hierarchy Call Instruction](../img/hlil-hierarchy-call.png)
+
+Be warned though! HLIL in particular is very tree-based. LLIL and MLIL are much safer to use the above paradigm of simply iterating through top-level instructions. 
+
+Make sure to also check out the specifics of each IL level for more details: [LLIL](https://docs.binary.ninja/dev/bnil-llil.html), [MLIL](https://docs.binary.ninja/dev/bnil-mlil.html) (HLIL not yet complete)
diff --git a/docs/img/hlil-hierarchy-call.png b/docs/img/hlil-hierarchy-call.png
new file mode 100644
index 00000000..184537de
--- /dev/null
+++ b/docs/img/hlil-hierarchy-call.png
diff --git a/docs/img/llil-hierarchy.png b/docs/img/llil-hierarchy.png
new file mode 100644
index 00000000..2f1264a4
--- /dev/null
+++ b/docs/img/llil-hierarchy.png