Clarify `get` and `get_ptr` in `core:container/small_array`.

See #5892.

1 files changed, 14 insertions, 4 deletions

diff --git a/core/container/small_array/small_array.odin b/core/container/small_array/small_array.odin
index a7e046fcf..b1674566d 100644
--- a/core/container/small_array/small_array.odin
+++ b/core/container/small_array/small_array.odin
@@ -105,8 +105,13 @@ This operation assumes that the small-array is large enough.
 
 This will result in:
 	- the value if 0 <= index < len
-	- the zero value of the type if len < index < capacity
-	- 'crash' if capacity < index or index < 0
+	- raise a bounds check error if capacity <= index
+	- the previous value if len < index < capacity, which defauls to T's zero value.
+
+	e.g. if you call `small_array.push(&a, 0, 1, 2)`, and `i := pop_back(&a)`,
+	then `get(a, 2)` will return the earlier value `2` at that location.
+
+	See also `get_safe`, which returns T's zero value and `false` if `index` is out of bounds.
 
 **Inputs**
 - `a`: The small-array
@@ -125,8 +130,13 @@ This operation assumes that the small-array is large enough.
 
 This will result in:
 	- the pointer if 0 <= index < len
-	- the pointer to the zero value if len < index < capacity
-	- 'crash' if capacity < index or index < 0
+	- raise a bounds check error if capacity <= index
+	- a pointer to the previous value if len < index < capacity, which defauls to T's zero value.
+
+	e.g. if you call `small_array.push(&a, 0, 1, 2)`, and `i := pop_back(&a)`,
+	then `get_ptr(a, 2)` will return a pointer to the slot containing the earlier value `2` at that location.
+
+	See also `get_ptr_safe`, which returns a nil pointer, and `false` if `index` is out of bounds.
 
 **Inputs**
 - `a`: A pointer to the small-array