more luamap documentation

docs/advanced/language-extensions.md

@@ -274,7 +274,7 @@ You can also map functions to table accessors (`__index` and `__newindex`). See
 
 ## Lua Table Types
 
-The `LuaTable` type is provided to allow direct creation and manipulation of Lua tables. This is useful if you want to use a table that uses types other than string for its keys, as that is not supported by TypeScript. Calls to lua method tables are translated to simple lua:
+The `LuaTable` type is provided to allow direct creation and manipulation of Lua tables. This is useful if you want to use a table that uses types other than string for its keys, as that is not supported by TypeScript. Calls to Lua method tables are translated to simple Lua:
 
 - `table.get(key)` Get a value by key -> `table[key]`
 - `table.set(key, value)` Set a value for key -> `table[key] = value`
@@ -328,7 +328,7 @@ print(#tbl)
 
 </SideBySide>
 
-### Iterating
+### Iterating over `LuaTable`
 
 To iterate over a `LuaTable`, use `for...of`. This will generate a `for...in` statement using `pairs()`.
 
@@ -366,11 +366,37 @@ end
 
 ### `LuaMap` and `LuaSet`
 
-Similar to `LuaTable`, the `LuaMap` and `LuaSet` types are provided to represent Lua tables used as a map or set. These are much more performant than the `Set`/`Map` classes, but do not come with all the same features (such as guaranteed insertion order).
+Similar to `LuaTable`, the `LuaMap` and `LuaSet` types are provided to represent Lua tables that are used as a map or a set. These are more performant than the `Set`/`Map` classes, but do not come with all of the same features (such as guaranteed insertion order).
 
-- `LuaMap` has the same methods as `LuaTable`, except that `table.get(key)` may also return `undefined`.
-- `LuaSet`, instead of `table.get/table.set`, has `table.add(value)`, which translates to `table[value] = true`.
-- There are also the readonly variants `ReadonlyLuaMap` and `ReadonlyLuaSet`.
+- `LuaMap` has the same methods as `LuaTable`. The exception is that the type of the return value for the `get` method is `V | undefined` instead of `V`, which makes it similar to how a `Map` works. (For this reason, we recommend using `LuaMap` over `LuaTable`, as it provides compiler-safety guarantees whenever you access a value.)
+- `LuaSet` does not have `get` and `set` methods. Instead, it has the `add` method, which transpiles to `table[value] = true`.
+- TSTL also provides the read-only variants of `ReadonlyLuaMap` and `ReadonlyLuaSet`, if needed.
+
+#### Iterating over `LuaMap` & `LuaSet`
+
+If you need to iterate over a `LuaMap` or a `LuaSet`, you do so in roughly the same way that you would for `LuaTable`:
+
+```ts
+const luaMap = new LuaMap();
+for (const [key, value] of luaMap) {
+}
+
+const luaSet = new LuaSet();
+for (const value of luaSet) {
+}
+```
+
+(Under the hood, both of these for loops would transpile to using `pairs` to iterate over the table.)
+
+#### Should I use `Map`/`Set` or `LuaMap`/`LuaSet`?
+
+`Map`/`Set` support more features than `LuaMap`/`LuaSet`. Namely, they have the `keys`, `entries`, `values`, and `clear` methods, a `size` attribute, and consistent iteration order (in the order of insertion). On the other hand, `LuaMap` and `LuaSet` transpile directly to a Lua table, so they are more lightweight.
+
+Thus, you might want to use `LuaMap`/`LuaSet`:
+
+- when the table needs to be serialized
+- when you need to interact with other Lua libraries
+- when you are in a critical path where the marginal improved performance would really matter (measure first!)
 
 ### Custom Getters and Setters