Edit "Core types" descriptions of Pair (mention KeyValue), RBMap (discourage its use), Span (make it's clear it's low level API), and String (clarify UTF-32 motivation).

Author: Ivorforce

engine_details/architecture/core_types.rst

@@ -142,7 +142,7 @@ scripting API.
 | Godot datatype        | Closest C++ STL datatype | Comment                                                                               |
 +=======================+==========================+=======================================================================================+
 | |string| 📜           | ``std::string``          | **Use this as the "default" string type.** ``String`` uses UTF-32 encoding            |
-|                       |                          | to improve performance thanks to its fixed character size.                            |
+|                       |                          | to simplify processing thanks to its fixed character size.                            |
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
 | |vector|              | ``std::vector``          | **Use this as the "default" vector type.** Uses copy-on-write (COW) semantics.        |
 |                       |                          | This means it's generally slower but can be copied around almost for free.            |
@@ -180,8 +180,10 @@ scripting API.
 |                       |                          | no heap allocations.                                                                  |
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
 | |span|                | ``std::span``            | Represents read-only access to a contiguous array without needing to copy any data.   |
-|                       |                          | See `pull request description <https://github.com/godotengine/godot/pull/100293>`__   |
-|                       |                          | for details.                                                                          |
+|                       |                          | Note that ``Span`` is designed to be a high performance API: It does not perform      |
+|                       |                          | parameter correctness checks in the same way you might be used to with other Godot    |
+|                       |                          | containers. Use with care.                                                            |
+|                       |                          | `Span` can be constructed from most array-like containers (e.g. ``vector.span()``).   |
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
 | |rb_set|              | ``std::set``             | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black_tree>`__              |
 |                       |                          | for faster access.                                                                    |
@@ -195,16 +197,18 @@ scripting API.
 |                       |                          | Use this map type when either of these affordances are needed. Use ``AHashMap``       |
 |                       |                          | otherwise.                                                                            |
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
-| |rb_map|              | ``std::map``             | Uses a `red-black tree <https://en.wikipedia.org/wiki/Red-black-tree>`__              |
-|                       |                          | for faster access.                                                                    |
+| |rb_map|              | ``std::map``             | Map type that uses a                                                                  |
+|                       |                          | `red-black tree <https://en.wikipedia.org/wiki/Red-black-tree>`__ to find keys.       |
+|                       |                          | The performance benefits of ``RBMap`` aren't established, so prefer using other types.|
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
 | |dictionary| 📜       | ``std::unordered_map``   | Keys and values can be of any Variant type. No static typing is imposed.              |
 |                       |                          | Uses shared reference counting, similar to ``std::shared_ptr``.                       |
 |                       |                          | Preserves insertion order. Uses ``HashMap<Variant>`` internally.                      |
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
 | |typed_dictionary| 📜 | ``std::unordered_map``   | Subclass of ``Dictionary`` but with static typing for its keys and values.            |
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
-| |pair|                | ``std::pair``            | Stores a single key-value pair.                                                       |
+| |pair|                | ``std::pair``            | Stores a single pair. See also ``KeyValue`` in the same file, which uses read-only    |
+|                       |                          | keys.                                                                                 |
 +-----------------------+--------------------------+---------------------------------------------------------------------------------------+
 
 .. |string| replace:: `String <https://github.com/godotengine/godot/blob/master/core/string/ustring.h>`__