How to Use Syntax in luau (function documentation)

This is for me and for yall.

What is function decumentation?

a function documentation is for me just a brief introduction to the function and what it does including
its arguments that are required or just optional arguments passed through to make our life
easier reusing old functions without needing to check what it does and what argument we need
especially when we are dealing with table arguments HELL! (for me at least)

Assigning types

local y = 1 -- normal variable type y == number
local y : number = 1 -- using the : we can assign a custom type
local y : string = 1 -- yes this wont error
y = (y::number) -- we can override the old type
print(y) -- still 1

now this was a brief understanding of what we will be descovering today using the : on a local
or variable will allow us to assign our own type of data to that variable it has no effect on its
value only on studio its only for us that way it can help us knowing what is string without typing
number_y = 0, string_x = “” and keeping track of whats what but now you may say

thats pretty useless who will ever use it and for what? im no rookie

lets use a better example

game.UserInputService.InputBegan:Connect(function(inputobj) ... end) 
-- sometimes function bug out and the studio won't show us the child of inputobj
-- like KeyCode, Parent, Name ... so we may take a guess what the child called
-- it may work or not let me show you how to deal with it like a chad
game."samestuff":Connect(function(inputobj : InputObject) ... end)
-- with assigning that type now our studio will know that inputobj =? inputobj
-- so it will show us inputobject children that will solve our problem of guessing game

if you still can’t believe we need this then let me introduce to you…

type variables

what is type?
type is just name it self it returns a type of a variable if it doesn’t find it
it will return UserData.

what is UserData?
game is a userdata anything that is not lua made data ex.(part, workspace, game…) is a userdata
we get a userdata by using typeof() its a roblox built in function does the same as type but
instead of userdata it returns the instance classes and names.

lua datas example (nil, string, number, table, function …)

local y = 1 -- normal variable
type(y) -- type of y == number
y = game
type(y) -- type of y == UserData
typeof(v) -- typeof y == game or what ever roblox named "game"

now what do i mean exactly with type variables?
have you wished mabey in your module script you could use : and access your module type?
what i mean exactly with this lets take a example

local module = {

local requirements = {...}

function module:execute(requirements : module.requirements)  end -- something like this
-- well this won't work because there is no module.requirements as a type variable
-- now lets make one
-- over here if we access requirements. it will not show anything because its a nil
-- or error type

type requirements = {[number] = string, x = number} -- x for dictionary [] for array
-- congratulations you new type value you can now assign it to your variables

function module:execute(requirements : requirements) end
-- it will automatically set the functions  argument 1 requirement to that type
-- you may ask and why all that work for 1 argument
-- just like the roblox inputobj example we may have complex systems
-- and we may forget deep table inputs but with assigning type we will
-- be able to see the children of the requirement it will be much easier to follow
-- and reusable we can also do this

function module:execute(requirements : {[number] : string ...}) end
-- but its more annoying because with complex tables we will go far like faaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaar your choice


Magic Patterns

just like string type syntax has its own magic words:
? – optional variable
“->” (without the “”) – function return only if () is used “() “->” nil”
() – can mean function and a seperatior like (1+1) +1 (x :string) & y :number
& – union operation just like 1+1 but for types without + a & b
{} – table, array, dictionary, metatable … indicator don’t confuse {} with () they are not the same
[] – table seperator {number : string} is not the same as {[number] : string}
| – seperator for multi options a : a | b | … thats what you see when you“”)
:: – type cast override a type or make a type instanely
! – can be used --!strict or --!nonstrict
… – for unlimited input
<> – generic used on tables to indicate that ALL the table values are that generic type <number…>
it has more functions but eh too complicated for my brain.
newproxy – return a new userdata metatable you can access with getmetatable and set with setmetatable.
export – its a function to export type variables works only in modules to other scripts since scripts cannot be reused or required like modules.

nil, string, any, unknown, userdata, number …
typeof has
game, Part, Player, Instance …

function documentation

basically we can document our function but we are limited to that since only roblox
function are documentated and there isn’t a feature who allow us to make the same
but we still have types to use in our functions

function foo() : boolean -- what the function suppose to return

function foo(name : string) -- argument documentation

function foo(list : "bike" |  "motor" | ...) -- this is how the scrolling method is done

function foo(...) -- this will print anything the function receives note ... is not a table

function foo(...)
local arg1, arg2, arg... = ... -- this is how you restruck the argument ...

function foo<T>(a:{T}) : {T} -- the T will be replaced of what you input

export type idkName : userdata -- must be inside a module script
local idk : require(path).userdata
local idk2 = (idk::nil) -- this will override the idk to nil type but not the value remember what we do here is just visualitation work

type n = string -- just a string
type A = {x: string} -- a simple table type
type B = {y: number}
type AB = A&B -- union of a and b
type AOB = A | B -- a or b
type option = {must = string, optional? = number} -- simple optional choice
type generic<inputt> = {x : inputt, y : inputt} -- what ever is input type are also the x and y

local fakecall : () -> "error" -- studio thinks this is a call when you atually call it it will error

-- this goes on and on Note this is only a visualisation help for people who have a hard
-- time undrestanding what the hell they have made up
-- roblox is not too strict with these methods but you can choose --!strict at the start
-- of your script to actually take these paramaters serious

-- PS 
-- everything we did is just the basics check out Luau Documentation for deeper information

now this thread may come back alive when luau actually gets --@params to go even deeper as we aren’t deep enough but im exited when it does please correct me if im wrong i just found this out today years old this generics remind me of old unity days C# used to have this never understood it as well not like its yall worries anyways enjoy


A good majority of this is already officially documented: Luau Lang. @params is LDoc spec, so not sure what you mean when you say “when Luau gets it”.

I’m not sure why you included userdata here but that section is wrong: type returns “nil” (the string, not a literal nil) in the case of the argument being nil. userdata is a vanilla Lua object that represnts a block of memory. Roblox instances and datatypes are userdata. typeof is a variant of type that respects Roblox datatypes (see Engine API). It will not return classes; you won’t see Player when you use typeof(game:GetService("Players"):GetPlayers()[1]). Any instance (those that live in the game tree) will return Instance when you use typeof.


This is incorrect syntax; it should be written as:

type option = {must: string, optional: number?}

well yes thats where i got my sources and for @param its not available in studio yet i know that
“-- @param …”
is the lua doc type as for C# we use xml or /// but like i said its not there for us to use
thats the whole point i don’t care if roblox can use it i only care about if we can use it. it will
be useless to tell people about learning lua doc items where there isn’t a sign of its arrival
in the end luau is just a sandbox of lua to restrict access to some actions its pretty understandable
since if that wasn’t the case roblox wouldn’t exists comming back to you i have tested it it won’t work
on my side im pretty sure because its not accessable on our side or mabey im wrong ?

its nice to know more about userdatas but the main idea was clear typing a instance will return userdata
as i said not i don’t want to get deep into userdatas yet because i think userdatas are just C datas who are kinda inserted somehow i don’t think i actually read that on lua page what ever it is its pretty cool.