added $range language extension and moved forRange annotation to deprecated section (#25)

Co-authored-by: Tom <tomblind@users.noreply.github.com>

Author: tomblind

docs/advanced/compiler-annotations.md

@@ -137,34 +137,6 @@ local inst = MyConstructor(3)
 
 </SideBySide>
 
-## @forRange
-
-**Target elements:** `declare function`
-
-Denotes a function declaration is a Lua numerical iterator. When used in a TypeScript `for...of` loop, the resulting Lua will use a numerical for loop.
-
-The function should not be a real function and an error will be thrown if it is used in any other way.
-
-**Example**
-
-<SideBySide>
-
-<!-- prettier-ignore -->
-```typescript
-/** @forRange */
-declare function forRange(start: number, limit: number, step?: number): number[];
-
-for (const i of forRange(1, 10)) {}
-for (const i of forRange(10, 1, -1)) {}
-```
-
-```lua
-for i = 1, 10 do end
-for i = 10, 1, -1 do end
-```
-
-</SideBySide>
-
 ## @luaIterator
 
 **Target elements:** `(declare) interface`
@@ -776,3 +748,50 @@ MyClass = __TS__Class()
 ```
 
 </SideBySide>
+
+## @forRange
+
+**Target elements:** `declare function`
+
+Denotes a function declaration is a Lua numerical iterator. When used in a TypeScript `for...of` loop, the resulting Lua will use a numerical for loop.
+
+The function should not be a real function and an error will be thrown if it is used in any other way.
+
+**Example**
+
+<SideBySide>
+
+<!-- prettier-ignore -->
+```typescript
+/** @forRange */
+declare function forRange(start: number, limit: number, step?: number): number[];
+
+for (const i of forRange(1, 10)) {}
+for (const i of forRange(10, 1, -1)) {}
+```
+
+```lua
+for i = 1, 10 do end
+for i = 10, 1, -1 do end
+```
+
+</SideBySide>
+
+**Upgrade Instructions**
+
+Use the [`$range` language extension](language-extensions.md#$range-iterator-function) instead of a custom annotated type.
+
+<SideBySide>
+
+<!-- prettier-ignore -->
+```typescript
+for (const i of $range(1, 10)) {}
+for (const i of $range(10, 1, -1)) {}
+```
+
+```lua
+for i = 1, 10 do end
+for i = 10, 1, -1 do end
+```
+
+</SideBySide>

docs/advanced/language-extensions.md

@@ -61,6 +61,29 @@ end
 foo, four = myFunc(nil)
 ```
 
+## $range Iterator Function
+
+Typescript's numeric for loops are less restrictive than Lua's, so they are transpiled into while loops instead. To create a Lua-style numeric for loop, you can use the `$range` language extension in a for...of loop.
+
+Example:
+
+<SideBySide>
+
+<!-- prettier-ignore -->
+```ts
+for (const i of $range(1, 5)) {}
+for (const i of $range(1, 10, 2)) {}
+for (const i of $range(5, 1, -1)) {}
+```
+
+```lua
+for i = 1, 5 do end
+for i = 1, 10, 2 do end
+for i = 5, 1, -1 do end
+```
+
+</SideBySide>
+
 ## Operator Map Types
 
 Lua supports overloading operators on types using [metatable methods](https://www.lua.org/manual/5.4/manual.html#2.4) such as `__add`. But, Javascript and Typescript do not support this. In order to use overloaded operators on types that support them, you can declare special mapping functions in TS that will translate to those operators in Lua.