chore: Documentation updates

Author: fuzzybinary

README.md

@@ -18,7 +18,7 @@ working, 🟨 - Partially working, ❌ - Not working)
 | Feature | Support | Note |
 | ------- | :-----: | ---- |
 | Dart as a Godot Extension Language | 🟨 |  |
-| Dart Debugging Extension | ✅ | Attach to `http://127.0.0.1:5858` |
+| Dart Debugging (VS Code) | ⚠ | See [Debugging](#debugging) |
 | Dart Available as a Scripting Language | 🟨 | Mostly usable in personal testing |
 | Hot Reload | ✅ | Hot Reload button now included. |
 | Simplified Binding using build_runner | 🟨 | Early implementation | 
@@ -267,13 +267,27 @@ position = pos;
 But in my opinion, this defeats the purpose of wrapping properties. Properties
 should mimic public member variables, and, when they can't, use methods instead.
 
+# Debugging
+
+Because of a change in the Dart SDK, you currently need to run the Dart Dev Service (DDS) in order to debug your game or Dart code in the Godot editor. To do so, with your game running, run the following in a terminal:
+
+```
+dart development-service --vm-service-uri=http://127.0.0.1:5858
+```
+
+I'm looking into ways to improve this experience in the long term.
+
 # Performance
 
 I have not measured the performance of this extension, partially because I know there is a lot of space for improvement in the
 embedding library itself, as well as in how the built in types are currently built.
 
 Once I've performed an optimization pass on the library, I'll look into measuring its performance.
 
+# Memory
+
+See [Memory](docs/memory.md)
+
 # More Info
 
 This utilizes my custom built Dart shared library for embedding Dart, the source

docs/memory.md

@@ -0,0 +1,22 @@
+# Memory
+
+`RefCounted` objects in Godot need special handling in garbage collected languages like Dart. 
+
+Any `RefCounted` object that is refernced by Dart adds one to its reference count, and its Script Instance Binding or Extension Instance Binding holds a handle to the Dart version of the object. However, Dart needs to know if it can safely garbage collect this object and release its reference to the `RefCounted` object, otherwise Dart will hold it forever and the object will leak.
+
+What Dart does is use the `referenced` callback of both Script Instance Bindings and Extension Instance Bindings to determine if it is the *only* reference to a `RefCounted`object.  If it is, the Godot Dart engine converts its reference to the object to *weak*, which means that if no objects in Dart are referencing it, it can safely be garbage collected.  If Dart is not the only reference, the Godot Dart engine changes its reference to *strong* so that even if no Dart objects are referencing the object, Dart doesn't accidentlly garbage collect a handle it needs to remain valid.
+
+To help make sense of the logic, here's a diagram:
+
+```mermaid
+flowchart TD
+    X(tieDartToNative) --> A{Is RefCounted?}
+    A -->|No| B(Hold String)
+    A -->|Yes| C(Hold Weak) --> D(initRef) --> E{Is RefCount > 1?}
+    E -->|Yes| F(Convert To Strong)
+    Y(reference callback) --> R{Is Incrementing?}
+    R -->|Yes| S{RefCount > 1?}
+    S -->|Yes| T(Hold Strong)
+    R -->|No| U{RefCount == 1?}
+    U -->|Yes| V(Hold Weak)
+```