Merge pull request #17 from SecondNewtonLaw/documentation-improvements

Documentation improvements

Author: senS24th

docs/Closures/getfunctionhash.md

@@ -39,7 +39,7 @@ local dummy_function_2 = function() end
 local dummy_function_3 = function() return "Constant" end
 local dummy_function_4 = function() return "Constant2" end
 
-print(is_sha384_hex(getfunctionhash(dummy_function0))) -- Output: true
+print(is_sha384_hex(getfunctionhash(dummy_function_0))) -- Output: true
 print(getfunctionhash(dummy_function_0) == getfunctionhash(dummy_function_1)) -- Output: false
 print(getfunctionhash(dummy_function_0) == getfunctionhash(dummy_function_2)) -- Output: true
 print(getfunctionhash(dummy_function_3) == getfunctionhash(dummy_function_4)) -- Output: false

docs/Closures/newcclosure.md

@@ -6,6 +6,14 @@
 
     The wrapped function **must** be yieldable, meaning that the function should be able to call [`#!luau task.wait`](https://create.roblox.com/docs/reference/engine/libraries/task#wait), for example.
 
+!!! failure "Error spoofing"
+
+    Luau and C errors are different. You must make sure that the error that closures wrapped with `#!luau newcclosure` appear as C closure errors!
+
+!!! info "Upvalues"
+
+    The function returned by `#!luau newcclosure` must have no upvalues.
+
 `#!luau newcclosure` takes any Lua function and wraps it into a C closure.
 When the returned function is called, it invokes the original Luau closure with the provided arguments, then passes the closure's returned values back to the caller.
 

docs/Environment/getgc.md

@@ -1,6 +1,6 @@
 # `getgc`
 
-`#!luau getgc` returns a list of all **non-dead garbage-collectable values**. These include functions, userdata, and optionally tables.
+`#!luau getgc` returns a list of **non-dead garbage-collectable values**. These include functions, userdata, and optionally tables.
 
 ```luau
 function getgc(includeTables: boolean?): { { any } | (...any) -> (...any) | userdata }

docs/Environment/getrenv.md

@@ -1,9 +1,9 @@
 # `getrenv`
 
 !!! warning "Adding `#!luau _G` and `#!luau shared`"
-    Make sure to properly implement _G and shared into the Roblox environemnt, as poor implementations will lead to detection vectors!
+    Make sure to properly implement `#!luau _G` and `#!luau shared` into the Roblox environemnt, as poor implementations will result in detection vectors!
 
-`#!luau getrenv` returns the **Roblox global environment**, which is used by game scripts. This environment is separate from the executor's environment returned by [`#!luau getgenv`](./getgenv.md).
+`#!luau getrenv` returns the **Roblox global environment**, which is used by the entire game. Changes to this environment will affect your executor environment as well.
 
 ```luau
 function getrenv(): { any }
@@ -24,5 +24,5 @@ getrenv().warn = "Hello!"
 print(type(warn)) -- Output: string
 
 getrenv().game = nil
-print(game) -- Output: nil (for scripts using the Roblox environment)
+print(game) -- Output: nil
 ```

docs/Scripts/getcallingscript.md

@@ -1,8 +1,8 @@
 # `getcallingscript`
 
-!!! info "Notes on `#!luau clonefunction`"
+!!! info "Notes on `#!luau getcallingscript`"
 
-    If a script is executing in a game thread, `#!luau getcallingscript()` must return the proper [`Script`](https://create.roblox.com/docs/reference/engine/classes/Script), [`LocalScript`](https://create.roblox.com/docs/reference/engine/classes/LocalScript), or [`ModuleScript`](https://create.roblox.com/docs/reference/engine/classes/ModuleScript) - even if it has set its global [`#!luau script`](https://create.roblox.com/docs/reference/engine/globals/RobloxGlobals#script) variable to `#!luau nil`.
+    If a game script is executing and `#!luau getcallingscript` is called it must return the proper [`Script`](https://create.roblox.com/docs/reference/engine/classes/Script), [`LocalScript`](https://create.roblox.com/docs/reference/engine/classes/LocalScript), or [`ModuleScript`](https://create.roblox.com/docs/reference/engine/classes/ModuleScript) - even if it has set its global [`#!luau script`](https://create.roblox.com/docs/reference/engine/globals/RobloxGlobals#script) variable to `#!luau nil`.
 
 `#!luau getcallingscript` returns the [`#!luau Script`](https://create.roblox.com/docs/reference/engine/classes/Script), [`#!luau LocalScript`](https://create.roblox.com/docs/reference/engine/classes/LocalScript), or [`#!luau ModuleScript`](https://create.roblox.com/docs/reference/engine/classes/ModuleScript) that **triggered the current code execution**.
 

docs/Scripts/getscriptclosure.md

@@ -1,8 +1,8 @@
 # `getscriptclosure`
 
-!!! info "Closure is generated, not directly reused"
+!!! info "Closure is compiled from bytecode, not an active one"
 
-    The function returned by `#!luau getscriptclosure` is a **new closure** compiled from the script's bytecode. It is not the same function used by the game, but behaves identically. This function is mostly used to retrieve constants from a script.
+    The function returned by `#!luau getscriptclosure` is a **new closure** compiled from the script's bytecode. It is not the function used by the game script, but has identical metadata. This function is used to retrieve constants from a script.
 
 !!! info "Not all scripts have bytecode"
 

docs/Scripts/loadstring.md

@@ -4,9 +4,8 @@
 
     Compiles the given string, and returns it runnable in a function. The environment must become unsafe after this function is called due to it allowing the modification of globals uncontrollably (see [setfenv](https://create.roblox.com/docs/reference/engine/globals/LuaGlobals#setfenv)/[getfenv](https://create.roblox.com/docs/reference/engine/globals/LuaGlobals#getfenv) documentation).
 
-
 ```luau
-function loadstring<A...>(source: string, chunkname: string?): ((A...) -> any | nil, string?)
+function loadstring<A..., T...>(source: string, chunkname: string?): (((A...) -> T...) | nil, string?)
 ```
 
 ## Parameters

docs/Signals/Connection.md

@@ -1,7 +1,7 @@
 # The `Connection` object
 
-!!! info "Notes on the `object`."
-    
+!!! info "Notes on the `object`"
+
     The retrieved connection object will only have the listed methods and fields, since it's a custom object
 
 A `#!luau Connection` object represents an active link to a signal's callback. These are returned by [`#!luau getconnections`](./getconnections.md) and allow inspection and manipulation over connections/signals.
@@ -20,7 +20,7 @@ A `#!luau Connection` object represents an active link to a signal's callback. T
 
 !!! info "Foreign and C-state behavior"
 
-    If the connection originates from a foreign Lua state or is a C-level connection, `#!luau Function` and `#!luau Thread` will be `#!luau nil`, due to these fields being impossible to obtain in this scenario.
+    If the connection originates from a foreign Lua state or is a C-level connection, `#!luau Function` and `#!luau Thread` will be `#!luau nil` and their `#!luau ForeignState` property will be `#!luau true`. This is due to neither `#!luau Function` nor `#!luau Thread` existing on the current Luau VM.
 
 ---
 

docs/Signals/firesignal.md

@@ -1,7 +1,10 @@
 # `firesignal`
 
-`#!luau firesignal` Invokes all Lua [`connections`](https://create.roblox.com/docs/reference/engine/datatypes/RBXScriptConnection) connected to a given [`RBXScriptSignal`](https://create.roblox.com/docs/reference/engine/datatypes/RBXScriptSignal).
+!!! info "Firing mode"
 
+    This function will invoke all the connections of the signal **immediately**, ignoring the [`#!luau Workspace.SignalBehaviour`](https://create.roblox.com/docs/reference/engine/classes/Workspace#SignalBehavior) property.
+
+`#!luau firesignal` Invokes all Lua [connections](https://create.roblox.com/docs/reference/engine/datatypes/RBXScriptConnection) connected to a given [`#!luau RBXScriptSignal`](https://create.roblox.com/docs/reference/engine/datatypes/RBXScriptSignal).
 
 ```luau
 function firesignal(signal: RBXScriptSignal, ...: any?)

docs/Signals/getconnections.md

@@ -1,12 +1,7 @@
 # `getconnections`
 
-!!! info "C and foreign signals"
-
-    Passing a signal that originates from [CoreScripts](https://robloxapi.github.io/ref/class/CoreScript.html), [Actors](https://create.roblox.com/docs/reference/engine/classes/Actor), or is otherwise made in C, will return a valid [`Connection`](./Connection.md) object - but its `#!luau Function` and `#!luau Thread` properties will be `#!luau nil`.
-
 `#!luau getconnections` retrieves a list of [`Connection`](./Connection.md) objects currently attached to a given [`RBXScriptSignal`](https://create.roblox.com/docs/reference/engine/datatypes/RBXScriptSignal).
 
-
 ```luau
 function getconnections(signal: RBXScriptSignal): {Connection}
 ```