From 4735a064d22d21256938e1ca3e9498fed6837a4c Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Sat, 4 May 2024 09:21:31 +0200
Subject: [PATCH 01/12] backend-guide - simple set up

---
 src/SUMMARY.md           |   3 +-
 src/backend_checklist.md | 204 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 206 insertions(+), 1 deletion(-)
 create mode 100644 src/backend_checklist.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index ef6f036..0a7c197 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -11,4 +11,5 @@
     - [Writeable](./writeable.md)
   - [Documentation](docs.md)
   - [Lifetimes](lifetimes.md)
-- [Backend developer guide](developer.md)
\ No newline at end of file
+- [Backend developer guide](developer.md)
+  - [Checklist](backend_checklist.md)
diff --git a/src/backend_checklist.md b/src/backend_checklist.md
new file mode 100644
index 0000000..95a1782
--- /dev/null
+++ b/src/backend_checklist.md
@@ -0,0 +1,204 @@
+How to create a backend is quite language dependent, and what is easier in one
+may be harder in another. Below we will start setting up a simple backend. We'll 
+show you how to set up a test in diplomat so you can start generating code quickly.
+Then we give you a template for a simple dynamic library that you can then link 
+to your host language. Finally we provide a suggested checklist for your backend.
+It is not automatically generated so when in doubt look at diplomat's [HIR](https://docs.rs/diplomat_core/latest/diplomat_core/hir/index.html)
+
+- [ ] **project structure**: You will need need to test your generated code so you should
+first set up a host language project. It should have all dependencies to be able to interface 
+with native code (or WASM).
+
+## Setting up basic code generation in a test
+
+Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
+and generate the required code for these. A good starting point is to create a test for generating a simple opaque struct
+without any methods: create a simple opaque type. Your backend should go in the tool create:
+create a module `tool/src/{backend}/mod.rs` (make sure you add a line `pub mod backend;` to `tool/src/lib.rs`).
+Add the following to it
+
+```rs
+use diplomat_core::hir::{OpaqueDef, TypeContext, TypeId};
+
+fn gen_opaque_def(ctx: &TypeContext, type_id: TypeId, opaque_path: &OpaqueDef) -> String {
+    "We'll get to it".into()
+}
+
+#[cfg(test)]
+mod test {
+    use diplomat_core::{
+        ast::{self},
+        hir::{self, TypeDef},
+    };
+    use quote::quote;
+
+    #[test]
+    fn test_opaque_gen() {
+        let tokens = quote! {
+            #[diplomat::bridge]
+            mod ffi {
+
+                #[diplomat::opaque]
+                struct OpaqueStruct;
+
+            }
+        };
+        let item = syn::parse2::<syn::File>(tokens).expect("failed to parse item ");
+
+        let diplomat_file = ast::File::from(&item);
+        let env = diplomat_file.all_types();
+        let attr_validator = hir::BasicAttributeValidator::new("my_backend_test");
+
+        let context = match hir::TypeContext::from_ast(&env, attr_validator) {
+            Ok(context) => context,
+            Err(e) => {
+                for (_cx, err) in e {
+                    eprintln!("Lowering error: {}", err);
+                }
+                panic!("Failed to create context")
+            }
+        };
+
+        let (type_id, opaque_def) = match context
+            .all_types()
+            .next()
+            .expect("Failed to generate first opaque def")
+        {
+            (type_id, TypeDef::Opaque(opaque_def)) => (type_id, opaque_def),
+            _ => panic!("Failed to find opaque type from AST"),
+        };
+
+        let generated = super::gen_opaque_def(&context, type_id, opaque_def);
+
+        insta::assert_snapshot!(generated)
+    }
+}
+```
+
+You can now run 
+```sh
+cargo test -p diplomat-tool -- backend::test --nocapture
+```
+You should also have a generated snapshot `diplomat_tool__backend__test__opaque_gen.snap.new` 
+which you can use to pick up your generated code.
+
+## How to generate the dylib
+Now to actually test native methods you will need to create a dynamically linked library 
+You should set up a separate rust project next to your diplomat fork e.g. `mybackendtest`
+```sh
+cargo new --lib mybackendtest
+```
+
+with the following Cargo.toml
+```toml
+[package]
+name = "mybackendtest"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+crate_type = ["cdylib"]
+name = "mybackendtest"
+
+[dependencies]
+diplomat = {path = "../diplomat/macro"}
+diplomat-runtime = {path = "../diplomat/runtime"}
+```
+Because you are using path dependencies, it is important that your library project be in 
+the same directory as your fork of diplomat
+
+Copy the following into your lib.rs
+```rs
+#[diplomat::bridge]
+mod ffi {
+
+    #[diplomat::opaque]
+    struct OpaqueStruct;
+
+    impl OpaqueStruct {
+        pub fn add_two(i: i32) -> i32 {
+            i + 2
+        }
+    }
+}
+
+```
+Note it is very important that the method be marked `pub` otherwise diplomat will ignore it.
+Now you can run 
+```sh
+cargo build
+```
+to create a debug artifact in `target/debug/libmybackendtest.dylib`
+
+## getting access to your native method
+
+Copy the impl block for `OpaqueStruct` into the test code underneath the `OpaqueStruct`,
+and update your gen code to the following which will generate the native symbol for your
+method:
+```rust
+use crate::c2::CFormatter;
+
+fn gen_opaque_def(ctx: &TypeContext, type_id: TypeId, opaque_path: &OpaqueDef) -> String {
+    let c_formatter = CFormatter::new(ctx);
+
+    opaque_def
+        .methods
+        .iter()
+        .map(|method| c_formatter.fmt_method_name(type_id, method))
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+```
+Now your snapshot should have the following contents
+```
+---
+source: tool/src/backend/mod.rs
+assertion_line: 67
+expression: generated
+---
+OpaqueStruct_add_two
+```
+where `OpaqueStruct_add_two` is the native symbol for your method. It has a simple signature `i32 -> i32`,
+so now you have a dynamic library and a symbol to load from it that you can start building. Now it is up
+to you to figure how to integrate these into your host language project skeleton.
+
+
+## Minimal Backend
+You should now work on building a minimal backend that can generate opaque type definitions
+with methods that only accept and return [**primitive types**](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.PrimitiveType.html).
+
+Once you have the basics of a backend you can add attribute handling. The best way to do this is to check the existing backends
+e.g. [dart](https://github.com/rust-diplomat/diplomat/blob/b3a8702f6736dbd6e667638ca0025b8f8cd1509f/tool/src/lib.rs#L95)(Note: git permalink may be out of date).
+The most important is to ignore disabled types and methods, as then you can take advantage of diplomat's feature tests
+and start building progressively.
+
+## Feature Tests
+Diplomat already includes feature tests that you can disable with `#[diplomat::attrs(disable, {backend})]`.
+As you add functionality to your backend you can progressively enable the types and methods for your
+backend. This way you can iterate with working examples.
+
+## backend checklist
+
+- [ ] [**primitive types**](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.PrimitiveType.html): This will be the most basic piece of the backend, and you will want
+to implement them early in order to test your ability to correctly call methods. 
+- [ ] [**opaque types**](): 
+  - [ ] basic definiton
+  - [ ] return a boxed opaque. This needs to be cleaned in managed languages.
+  You can use the autogenerated `{OpaqueName}_destroy({OpaqueName}*)` native method to clean up 
+  the memory of the associated opaque.
+  - [ ] as self parameter
+  - [ ] as another parameter
+- [ ] structs
+- [ ] enums
+- [ ] writeable
+- [ ] slices
+  - [ ] primitive slices
+  - [ ] str slices
+  - [ ] owned slices should be kotlin arrays
+  - [ ] slices of strings
+- [ ] strings
+- [ ] borrows
+  - [ ] borrows of parameters
+  - [ ] in struct fields
+- [ ] nullables
+- [ ] fallibles

From f460e8730286a8febaa14cde57b6d72953d12ef6 Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Sat, 4 May 2024 15:17:07 +0200
Subject: [PATCH 02/12] backend-guide

---
 src/SUMMARY.md                                |  2 +-
 ...kend_checklist.md => backend_dev_setup.md} | 34 ++++++++++++-------
 2 files changed, 22 insertions(+), 14 deletions(-)
 rename src/{backend_checklist.md => backend_dev_setup.md} (83%)

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 0a7c197..8a321d7 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -12,4 +12,4 @@
   - [Documentation](docs.md)
   - [Lifetimes](lifetimes.md)
 - [Backend developer guide](developer.md)
-  - [Checklist](backend_checklist.md)
+  - [Backend development setup](backend_dev_setup.md)
diff --git a/src/backend_checklist.md b/src/backend_dev_setup.md
similarity index 83%
rename from src/backend_checklist.md
rename to src/backend_dev_setup.md
index 95a1782..4985267 100644
--- a/src/backend_checklist.md
+++ b/src/backend_dev_setup.md
@@ -1,3 +1,4 @@
+# How to Set up a Minimal Backend
 How to create a backend is quite language dependent, and what is easier in one
 may be harder in another. Below we will start setting up a simple backend. We'll 
 show you how to set up a test in diplomat so you can start generating code quickly.
@@ -9,7 +10,7 @@ It is not automatically generated so when in doubt look at diplomat's [HIR](http
 first set up a host language project. It should have all dependencies to be able to interface 
 with native code (or WASM).
 
-## Setting up basic code generation in a test
+## Setting up Basic Code Generation in a Test
 
 Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
 and generate the required code for these. A good starting point is to create a test for generating a simple opaque struct
@@ -82,7 +83,7 @@ cargo test -p diplomat-tool -- backend::test --nocapture
 You should also have a generated snapshot `diplomat_tool__backend__test__opaque_gen.snap.new` 
 which you can use to pick up your generated code.
 
-## How to generate the dylib
+## How to Generate the Dylib
 Now to actually test native methods you will need to create a dynamically linked library 
 You should set up a separate rust project next to your diplomat fork e.g. `mybackendtest`
 ```sh
@@ -130,7 +131,7 @@ cargo build
 ```
 to create a debug artifact in `target/debug/libmybackendtest.dylib`
 
-## getting access to your native method
+## Getting Access to your Native Method
 
 Copy the impl block for `OpaqueStruct` into the test code underneath the `OpaqueStruct`,
 and update your gen code to the following which will generate the native symbol for your
@@ -175,9 +176,16 @@ and start building progressively.
 ## Feature Tests
 Diplomat already includes feature tests that you can disable with `#[diplomat::attrs(disable, {backend})]`.
 As you add functionality to your backend you can progressively enable the types and methods for your
-backend. This way you can iterate with working examples.
+backend. This way you can iterate with working examples. These are called via [cargo-make](https://sagiegurari.github.io/cargo-make/)
+e.g
+```sh
+cargo make gen-dart-feature
+```
+You can look at `Makefile.toml` to see how tasks are defined. Most of the generative tasks make use of this
+[duckscript function](https://github.com/rust-diplomat/diplomat/blob/b3a8702f6736dbd6e667638ca0025b8f8cd1509f/support/functions.ds#L1)
+([Duckscript](https://sagiegurari.github.io/duckscript/) is a simple scripting language)
 
-## backend checklist
+## Backend Checklist
 
 - [ ] [**primitive types**](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.PrimitiveType.html): This will be the most basic piece of the backend, and you will want
 to implement them early in order to test your ability to correctly call methods. 
@@ -188,17 +196,17 @@ to implement them early in order to test your ability to correctly call methods.
   the memory of the associated opaque.
   - [ ] as self parameter
   - [ ] as another parameter
-- [ ] structs
-- [ ] enums
-- [ ] writeable
-- [ ] slices
+- [ ] [**structs**](https://docs.rs/diplomat_core/0.7.0/diplomat_core/hir/struct.StructDef.html)
+- [ ] [**enums**](https://docs.rs/diplomat_core/0.7.0/diplomat_core/hir/struct.EnumDef.html)
+- [ ] [**writeable**](https://docs.rs/diplomat_core/0.7.0/diplomat_core/hir/enum.SuccessType.html#variant.Writeable)
+- [ ] [**slices**](https://docs.rs/diplomat_core/0.7.0/diplomat_core/hir/enum.Slice.html)
   - [ ] primitive slices
   - [ ] str slices
   - [ ] owned slices should be kotlin arrays
   - [ ] slices of strings
-- [ ] strings
-- [ ] borrows
+  - [ ] strings
+- [ ] borrows. This is probably one of the trickiest things., as you need to ma
   - [ ] borrows of parameters
   - [ ] in struct fields
-- [ ] nullables
-- [ ] fallibles
+- [ ] nullables, i.e. returning option types.
+- [ ] fallibles, i.e. returning result types. The resulting native type will be a discriminated union 

From b32e2524e857dc90a34345a9607dacacc89098dc Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Sat, 4 May 2024 15:32:03 +0200
Subject: [PATCH 03/12] backend-guide - clean up text

---
 src/backend_dev_setup.md | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/src/backend_dev_setup.md b/src/backend_dev_setup.md
index 4985267..986a7d7 100644
--- a/src/backend_dev_setup.md
+++ b/src/backend_dev_setup.md
@@ -14,9 +14,8 @@ with native code (or WASM).
 
 Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
 and generate the required code for these. A good starting point is to create a test for generating a simple opaque struct
-without any methods: create a simple opaque type. Your backend should go in the tool create:
-create a module `tool/src/{backend}/mod.rs` (make sure you add a line `pub mod backend;` to `tool/src/lib.rs`).
-Add the following to it
+without any methods. Your backend should go in the tool create: create a module `tool/src/{backend}/mod.rs` 
+(make sure you add a line `pub mod backend;` to `tool/src/lib.rs`). Add the following to it
 
 ```rs
 use diplomat_core::hir::{OpaqueDef, TypeContext, TypeId};
@@ -133,9 +132,10 @@ to create a debug artifact in `target/debug/libmybackendtest.dylib`
 
 ## Getting Access to your Native Method
 
-Copy the impl block for `OpaqueStruct` into the test code underneath the `OpaqueStruct`,
-and update your gen code to the following which will generate the native symbol for your
-method:
+Now we can add code that will iterate over all of the methods of the opaque struct.
+First, copy the impl block for `OpaqueStruct` into the test code underneath the `OpaqueStruct`.
+Next, update your the code for `gen_opaque_def` to the following which will generate the native 
+symbol for your new impl method:
 ```rust
 use crate::c2::CFormatter;
 
@@ -168,6 +168,8 @@ to you to figure how to integrate these into your host language project skeleton
 You should now work on building a minimal backend that can generate opaque type definitions
 with methods that only accept and return [**primitive types**](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.PrimitiveType.html).
 
+You will need to update `tool/src/lib.rs` to add handling for your backend.
+
 Once you have the basics of a backend you can add attribute handling. The best way to do this is to check the existing backends
 e.g. [dart](https://github.com/rust-diplomat/diplomat/blob/b3a8702f6736dbd6e667638ca0025b8f8cd1509f/tool/src/lib.rs#L95)(Note: git permalink may be out of date).
 The most important is to ignore disabled types and methods, as then you can take advantage of diplomat's feature tests
@@ -175,8 +177,9 @@ and start building progressively.
 
 ## Feature Tests
 Diplomat already includes feature tests that you can disable with `#[diplomat::attrs(disable, {backend})]`.
-As you add functionality to your backend you can progressively enable the types and methods for your
-backend. This way you can iterate with working examples. These are called via [cargo-make](https://sagiegurari.github.io/cargo-make/)
+where `{backend}` refers to your new backend. As you add functionality to your backend you 
+can progressively enable the types and methods for your backend. This way you can iterate with 
+working examples. These are called via [cargo-make](https://sagiegurari.github.io/cargo-make/)
 e.g
 ```sh
 cargo make gen-dart-feature

From f396e3e591449ce5d9ef18328cf23821dddc9ee9 Mon Sep 17 00:00:00 2001
From: jcrist1 <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 21:30:03 +0200
Subject: [PATCH 04/12] Update src/backend_dev_setup.md

Co-authored-by: Manish Goregaokar <manishsmail@gmail.com>
---
 src/backend_dev_setup.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/backend_dev_setup.md b/src/backend_dev_setup.md
index 986a7d7..ae4b055 100644
--- a/src/backend_dev_setup.md
+++ b/src/backend_dev_setup.md
@@ -14,7 +14,7 @@ with native code (or WASM).
 
 Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
 and generate the required code for these. A good starting point is to create a test for generating a simple opaque struct
-without any methods. Your backend should go in the tool create: create a module `tool/src/{backend}/mod.rs` 
+without any methods. Your backend should go in the tool crate: create a module `tool/src/{backend}/mod.rs` 
 (make sure you add a line `pub mod backend;` to `tool/src/lib.rs`). Add the following to it
 
 ```rs

From bf84b5fc99c7b749cb06f829c2faea1dd7ab023a Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 21:37:53 +0200
Subject: [PATCH 05/12] backend-guide - address review comments

---
 src/SUMMARY.md           |  2 +-
 src/backend_dev_setup.md | 11 +++++++----
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 8a321d7..bf983ab 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -12,4 +12,4 @@
   - [Documentation](docs.md)
   - [Lifetimes](lifetimes.md)
 - [Backend developer guide](developer.md)
-  - [Backend development setup](backend_dev_setup.md)
+- [Backend development setup](backend_dev_setup.md)
diff --git a/src/backend_dev_setup.md b/src/backend_dev_setup.md
index 986a7d7..2f54213 100644
--- a/src/backend_dev_setup.md
+++ b/src/backend_dev_setup.md
@@ -82,8 +82,10 @@ cargo test -p diplomat-tool -- backend::test --nocapture
 You should also have a generated snapshot `diplomat_tool__backend__test__opaque_gen.snap.new` 
 which you can use to pick up your generated code.
 
-## How to Generate the Dylib
-Now to actually test native methods you will need to create a dynamically linked library 
+## How to Generate  the library
+Now to actually test native methods you will need to create some kind of library be it static, dynamic or
+even WASM. In the following we will be creating a dynamically linked library.
+
 You should set up a separate rust project next to your diplomat fork e.g. `mybackendtest`
 ```sh
 cargo new --lib mybackendtest
@@ -208,8 +210,9 @@ to implement them early in order to test your ability to correctly call methods.
   - [ ] owned slices should be kotlin arrays
   - [ ] slices of strings
   - [ ] strings
-- [ ] borrows. This is probably one of the trickiest things., as you need to ma
+- [ ] borrows. This is probably one of the trickiest things, as you need to ensure that managed objects don't get
+cleaned up if something depends on them.
   - [ ] borrows of parameters
   - [ ] in struct fields
 - [ ] nullables, i.e. returning option types.
-- [ ] fallibles, i.e. returning result types. The resulting native type will be a discriminated union 
+- [ ] fallibles, i.e. returning result types. The resulting native type will be a discriminated union.

From ae81633a8f2acbdd687c24cec585c2bcc9d43cf0 Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 21:53:32 +0200
Subject: [PATCH 06/12] backend-guide - more in-depth

---
 src/SUMMARY.md           |  3 +--
 src/backend_dev_setup.md | 11 ++++++++++-
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index bf983ab..f387ad4 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -11,5 +11,4 @@
     - [Writeable](./writeable.md)
   - [Documentation](docs.md)
   - [Lifetimes](lifetimes.md)
-- [Backend developer guide](developer.md)
-- [Backend development setup](backend_dev_setup.md)
+- [Backend developer guide](backend_dev_setup.md)
diff --git a/src/backend_dev_setup.md b/src/backend_dev_setup.md
index 50e4395..f852f19 100644
--- a/src/backend_dev_setup.md
+++ b/src/backend_dev_setup.md
@@ -13,7 +13,16 @@ with native code (or WASM).
 ## Setting up Basic Code Generation in a Test
 
 Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
-and generate the required code for these. A good starting point is to create a test for generating a simple opaque struct
+and generate the required code for these. To do that we start with an 
+[`ast::File`](https://docs.rs/diplomat_core/latest/diplomat_core/ast/struct.File.html), which can then be 
+parsed into a [`Env`](https://docs.rs/diplomat_core/latest/diplomat_core/struct.Env.html) using the 
+`all_types` method. Then we can create the [`TypeContext`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html)
+which is generated using the [`from_ast`]( https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html#method.from_ast)
+method. You will also need an [`AttributeValidator`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/trait.AttributeValidator.html), but
+should probably start with the simple [`BasicAttributeValidator`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.BasicAttributeValidator.html).
+
+
+A good starting point is to create a test for generating a simple opaque struct
 without any methods. Your backend should go in the tool crate: create a module `tool/src/{backend}/mod.rs` 
 (make sure you add a line `pub mod backend;` to `tool/src/lib.rs`). Add the following to it
 

From 1baaf31e80ba3a0eedac7d4b46b19a4dbd6cf124 Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 21:59:08 +0200
Subject: [PATCH 07/12] backend-guide

---
 src/backend_dev_setup.md | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/src/backend_dev_setup.md b/src/backend_dev_setup.md
index f852f19..5651019 100644
--- a/src/backend_dev_setup.md
+++ b/src/backend_dev_setup.md
@@ -14,17 +14,23 @@ with native code (or WASM).
 
 Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
 and generate the required code for these. To do that we start with an 
-[`ast::File`](https://docs.rs/diplomat_core/latest/diplomat_core/ast/struct.File.html), which can then be 
-parsed into a [`Env`](https://docs.rs/diplomat_core/latest/diplomat_core/struct.Env.html) using the 
-`all_types` method. Then we can create the [`TypeContext`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html)
-which is generated using the [`from_ast`]( https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html#method.from_ast)
-method. You will also need an [`AttributeValidator`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/trait.AttributeValidator.html), but
-should probably start with the simple [`BasicAttributeValidator`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.BasicAttributeValidator.html).
+[`ast::File`](https://docs.rs/diplomat_core/latest/diplomat_core/ast/struct.File.html), which can 
+then be parsed into a [`Env`](https://docs.rs/diplomat_core/latest/diplomat_core/struct.Env.html)
+using the `all_types` method. Then we can create the 
+[`TypeContext`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html) 
+which is generated using the 
+[`from_ast`]( https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html#method.from_ast)
+method. You will also need an 
+[`AttributeValidator`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/trait.AttributeValidator.html), 
+but should probably start with the simple 
+[`BasicAttributeValidator`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.BasicAttributeValidator.html).
 
 
-A good starting point is to create a test for generating a simple opaque struct
-without any methods. Your backend should go in the tool crate: create a module `tool/src/{backend}/mod.rs` 
-(make sure you add a line `pub mod backend;` to `tool/src/lib.rs`). Add the following to it
+
+We will now build an example by way of a test. A good starting point is to create a test for
+generating a simple opaque struct without any methods. Your backend should go in the tool crate: 
+create a module `tool/src/{backend}/mod.rs`  (make sure you add a line `pub mod backend;` to 
+`tool/src/lib.rs`). Add the following to it
 
 ```rs
 use diplomat_core::hir::{OpaqueDef, TypeContext, TypeId};
@@ -91,7 +97,7 @@ cargo test -p diplomat-tool -- backend::test --nocapture
 You should also have a generated snapshot `diplomat_tool__backend__test__opaque_gen.snap.new` 
 which you can use to pick up your generated code.
 
-## How to Generate  the library
+## How to Generate the Library
 Now to actually test native methods you will need to create some kind of library be it static, dynamic or
 even WASM. In the following we will be creating a dynamically linked library.
 

From 88a86e478c3942a1c1e8d91c37f6016799326afb Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 22:00:18 +0200
Subject: [PATCH 08/12] backend-guide - rename file

---
 src/SUMMARY.md                            |  2 +-
 src/developer.md                          | 20 --------------------
 src/{backend_dev_setup.md => developr.md} |  0
 3 files changed, 1 insertion(+), 21 deletions(-)
 delete mode 100644 src/developer.md
 rename src/{backend_dev_setup.md => developr.md} (100%)

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index f387ad4..51a466c 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -11,4 +11,4 @@
     - [Writeable](./writeable.md)
   - [Documentation](docs.md)
   - [Lifetimes](lifetimes.md)
-- [Backend developer guide](backend_dev_setup.md)
+- [Backend developer guide](developer.md)
diff --git a/src/developer.md b/src/developer.md
deleted file mode 100644
index ab01092..0000000
--- a/src/developer.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Backend Developer Guide
-
-
-This is yet to be fleshed out. In general, if trying to write a backend, please use the [Diplomat HIR] ("higher level IR"). This is similar to a syntax tree but is far easier to work with, with paths being pre-resolved and a bunch of invalid states being unrepresentable.
-
-
-It's obtained from a [`TypeContext`], which is itself constructed from an [`Env`], from an [`ast::File`], which can be constructed from a `syn` module covering the entire crate.
-
-
-Currently Diplomat has `c2` and `cpp2` backends that use the HIR. The other backends still use the AST, but we hope to move off of that. We recommend you look at the `c2` and `cpp2` backends of `diplomat-tool` to understand how to implement your own backend.
-
-
-You can write a new backend as a standalone library, or as a module under `tool`. The Diplomat team is happy to accept new modules but may not necessarily commit to keeping them working when Diplomat changes. We promise to notify you if such a module breaks, and will always try to fix things when it's a minor change.
-
-
-
- [Diplomat HIR]: https://docs.rs/diplomat_core/latest/diplomat_core/hir/index.html
- [`TypeContext`]: https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html
- [`Env`]: https://docs.rs/diplomat_core/latest/diplomat_core/struct.Env.html
- [`ast::File`]: https://docs.rs/diplomat_core/latest/diplomat_core/ast/struct.File.html
\ No newline at end of file
diff --git a/src/backend_dev_setup.md b/src/developr.md
similarity index 100%
rename from src/backend_dev_setup.md
rename to src/developr.md

From 38076d6b93c6c09abe851f8b738ed7dec41ae25f Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 22:03:23 +0200
Subject: [PATCH 09/12] backend-guide - link to method

---
 src/developr.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/developr.md b/src/developr.md
index 5651019..a8a0f1f 100644
--- a/src/developr.md
+++ b/src/developr.md
@@ -16,7 +16,9 @@ Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/la
 and generate the required code for these. To do that we start with an 
 [`ast::File`](https://docs.rs/diplomat_core/latest/diplomat_core/ast/struct.File.html), which can 
 then be parsed into a [`Env`](https://docs.rs/diplomat_core/latest/diplomat_core/struct.Env.html)
-using the `all_types` method. Then we can create the 
+using the 
+[`all_types`](https://docs.rs/diplomat_core/latest/diplomat_core/ast/struct.File.html#method.all_types) 
+method. Then we can create the 
 [`TypeContext`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html) 
 which is generated using the 
 [`from_ast`]( https://docs.rs/diplomat_core/latest/diplomat_core/hir/struct.TypeContext.html#method.from_ast)

From 40ff9966dbe0ef4f36fdd89ba1d4cdc9e2506cc0 Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 22:04:04 +0200
Subject: [PATCH 10/12] backend-guide - consistent type link formatting

---
 src/developr.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/developr.md b/src/developr.md
index a8a0f1f..5cf948e 100644
--- a/src/developr.md
+++ b/src/developr.md
@@ -12,7 +12,7 @@ with native code (or WASM).
 
 ## Setting up Basic Code Generation in a Test
 
-Your backend should iterate over all [TypeDefs](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
+Your backend should iterate over all [`TypeDefs`](https://docs.rs/diplomat_core/latest/diplomat_core/hir/enum.TypeDef.html)
 and generate the required code for these. To do that we start with an 
 [`ast::File`](https://docs.rs/diplomat_core/latest/diplomat_core/ast/struct.File.html), which can 
 then be parsed into a [`Env`](https://docs.rs/diplomat_core/latest/diplomat_core/struct.Env.html)

From 8a6246e2d1cdc0171d3a42248b368471ba443561 Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 14 May 2024 22:06:44 +0200
Subject: [PATCH 11/12] backend - commas

---
 src/developr.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/developr.md b/src/developr.md
index 5cf948e..c8f45b8 100644
--- a/src/developr.md
+++ b/src/developr.md
@@ -100,7 +100,7 @@ You should also have a generated snapshot `diplomat_tool__backend__test__opaque_
 which you can use to pick up your generated code.
 
 ## How to Generate the Library
-Now to actually test native methods you will need to create some kind of library be it static, dynamic or
+Now to actually test native methods you will need to create some kind of library, be it static, dynamic, or
 even WASM. In the following we will be creating a dynamically linked library.
 
 You should set up a separate rust project next to your diplomat fork e.g. `mybackendtest`

From 2934b5cca9b8911a0426b5db175b58505fd59a36 Mon Sep 17 00:00:00 2001
From: Jan Cristina <jan.cristina@gmail.com>
Date: Tue, 21 May 2024 20:59:12 +0200
Subject: [PATCH 12/12] backend-guide

---
 src/{developr.md => developer.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename src/{developr.md => developer.md} (100%)

diff --git a/src/developr.md b/src/developer.md
similarity index 100%
rename from src/developr.md
rename to src/developer.md