@quenty/binder 4.4.1-canary.8533eea.0 → 4.5.1

package/CHANGELOG.md

@@ -3,12 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.4.1-canary.8533eea.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/binder@4.4.0...@quenty/binder@4.4.1-canary.8533eea.0) (2021-12-18)
+## [4.5.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/binder@4.5.0...@quenty/binder@4.5.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/binder
+
+
+
+
+
+# [4.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/binder@4.4.0...@quenty/binder@4.5.0) (2021-12-18)
 
 
 ### Bug Fixes
 
-* Binder was not deconstructing correctly on cleanup ([3cd1847](https://github.com/Quenty/NevermoreEngine/commit/3cd1847ccc7100cdc14ed77242f47e46a061da56))
+* Binder was not deconstructing correctly on cleanup ([b6cd547](https://github.com/Quenty/NevermoreEngine/commit/b6cd54746457afe180ddda2f4d41731b29c144a5))
 
 
 

package/README.md

@@ -1,10 +1,10 @@
 ## Binder
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
@@ -13,109 +13,9 @@
 
 Binders bind a class to Roblox Instance
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/Binder">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/binder --save
-```
-
-## Usage
-
-```lua
--- Setup a class!
-local MyClass = {}
-MyClass.__index = MyClass
-
-function MyClass.new(robloxInstance)
-	print("New tagged instance of ", robloxInstance)
-	return setmetatable({}, MyClass)
-end
-
-function MyClass:Destroy()
-	print("Cleaning up")
-	setmetatable(self, nil)
-end
-
--- bind to every instance with tag of "TagName"!
-local binder = Binder.new("TagName", MyClass)
-binder:Start() -- listens for new instances and connects events
-```
-
-## API
-
-### `Binder.new(tagName, constructor)`
-Creates a new binder object.
-
-### `Binder.isBinder(value)`
-Retrieves whether or not its a binder
-
-### `Binder:Start()`
-Listens for new instances and connects to the GetInstanceAddedSignal() and removed signal!
-
-### `Binder:GetTag()`
-Returns the tag name that the binder has
-
-### `Binder:GetConstructor()`
-Returns whatever was set for the construtor. Used for meta-analysis of the binder, such as extracting new
-
-### `Binder:ObserveInstance(inst, callback)`
-Fired when added, and then after removal, but before destroy!
-
-### `Binder:GetClassAddedSignal()`
-Returns a new signal that will fire whenever a class is bound to the binder
-
-### `Binder:GetClassRemovingSignal()`
-Returns a new signal that will fire whenever a class is removed from the binder
-
-### `Binder:GetAll()`
-Returns all of the classes in a new table
-
-```lua
-local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
-
--- Update every bird every frame
-RunService.Stepped:Connect(function()
-	for _, bird in pairs(birdBinder:GetAll()) do
-		bird:Update()
-	end
-end)
-
-```
-### `Binder:GetAllSet()`
-Faster method to get all items in a binder
-
-NOTE: Do not mutate this set directly
-
-```lua
-local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
-
--- Update every bird every frame
-RunService.Stepped:Connect(function()
-	for bird, _ in pairs(birdBinder:GetAllSet()) do
-		bird:Update()
-	end
-end)
-
-birdBinder:Start()
-```
-
-### `Binder:Bind(inst)`
-Binds an instance to this binder using collection service and attempts to return it if it's bound properly. See BinderUtils.promiseBoundClass() for a safe way to retrieve it.
-
-NOTE: Do not assume that a bound object will be retrieved
-
-### `Binder:Unbind(inst)`
-Unbinds the instance by removing the tag
-
-### `Binder:BindClient(inst)`
-See :Bind(). Acknowledges the risk of doing this on the client. Using this acknowledges that we're intentionally binding on a safe client object, i.e. one without replication. If another tag is changed on this instance, this tag will be lost/changed.
-
-### `Binder:UnbindClient(inst)`
-See Unbind(), acknowledges risk of doing this on the client.
-
-### `Binder:Get(inst)`
-Returns a version of the clas
-
-### `Binder:Promise(inst, cancelToken)`
-
-### `Binder:Destroy()`
-Cleans up all bound classes, and disconnects all events
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/binder",
-  "version": "4.4.1-canary.8533eea.0",
+  "version": "4.5.1",
   "description": "Utility object to Bind a class to Roblox object, and associated helper methods",
   "keywords": [
     "Roblox",
@@ -25,18 +25,18 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "3.2.0",
-    "@quenty/brio": "3.4.1-canary.8533eea.0",
-    "@quenty/instanceutils": "3.4.1-canary.8533eea.0",
-    "@quenty/linkutils": "3.4.1-canary.8533eea.0",
-    "@quenty/loader": "3.1.1",
-    "@quenty/maid": "2.0.1",
-    "@quenty/promise": "3.2.1-canary.8533eea.0",
-    "@quenty/signal": "2.0.0",
-    "@quenty/valueobject": "3.4.1-canary.8533eea.0"
+    "@quenty/baseobject": "^3.2.1",
+    "@quenty/brio": "^3.5.1",
+    "@quenty/instanceutils": "^3.5.1",
+    "@quenty/linkutils": "^3.5.1",
+    "@quenty/loader": "^3.1.2",
+    "@quenty/maid": "^2.0.2",
+    "@quenty/promise": "^3.3.1",
+    "@quenty/signal": "^2.0.1",
+    "@quenty/valueobject": "^3.5.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8533eeade3bf6835c0295785c1c326b9abee3222"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Shared/Binder.lua

@@ -1,5 +1,28 @@
---- Bind class to Roblox Instance
--- @classmod Binder
+--[=[
+	Bind class to Roblox Instance
+
+	```lua
+	-- Setup a class!
+	local MyClass = {}
+	MyClass.__index = MyClass
+
+	function MyClass.new(robloxInstance)
+		print("New tagged instance of ", robloxInstance)
+		return setmetatable({}, MyClass)
+	end
+
+	function MyClass:Destroy()
+		print("Cleaning up")
+		setmetatable(self, nil)
+	end
+
+	-- bind to every instance with tag of "TagName"!
+	local binder = Binder.new("TagName", MyClass)
+	binder:Start() -- listens for new instances and connects events
+	```
+
+	@class Binder
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,37 +33,37 @@ local Maid = require("Maid")
 local MaidTaskUtils = require("MaidTaskUtils")
 local Signal = require("Signal")
 local promiseBoundClass = require("promiseBoundClass")
---[[
-@usage
-
--- Setup a class!
-local MyClass = {}
-MyClass.__index = MyClass
-
-function MyClass.new(robloxInstance)
-	print("New tagged instance of ", robloxInstance)
-	return setmetatable({}, MyClass)
-end
-
-function MyClass:Destroy()
-	print("Cleaning up")
-	setmetatable(self, nil)
-end
-
--- bind to every instance with tag of "TagName"!
-local binder = Binder.new("TagName", MyClass)
-binder:Start() -- listens for new instances and connects events
-]]
 
 local Binder = {}
 Binder.__index = Binder
 Binder.ClassName = "Binder"
 
---- Creates a new binder object.
--- @constructor Binder.new(tagName, constructor)
--- @param tagName Name of the tag to bind to. This uses CollectionService's tag system
--- @param constructor A constructor to create the new class. Comes in three flavors.
--- @treturn Binder
+--[=[
+	Constructor for a binder
+	@type BinderContructor (Instance, ...: any) -> T | { new: (Instance, ...: any) } | { Create(self, Instance, ...: any) }
+	@within Binder
+]=]
+
+--[=[
+	Constructs a new binder object.
+
+	```lua
+	local binder = Binder.new("Bird", function(inst)
+		print("Wow, a new bird!", inst)
+
+		return {
+			Destroy = function()
+				print("Uh oh, the bird is gone!")
+			end;
+		}
+	end)
+	binder:Start()
+	```
+	@param tagName string -- Name of the tag to bind to. This uses CollectionService's tag system
+	@param constructor BinderContructor
+	@param ... any -- Variable arguments that will be passed into the constructor
+	@return Binder<T>
+]=]
 function Binder.new(tagName, constructor, ...)
 	local self = setmetatable({}, Binder)
 
@@ -55,7 +78,7 @@ function Binder.new(tagName, constructor, ...)
 	self._listeners = {} -- [inst] = callback
 	self._args = {...}
 
-	delay(5, function()
+	task.delay(5, function()
 		if not self._loaded then
 			warn(("Binder %q is not loaded. Call :Start() on it!"):format(self._tagName))
 		end
@@ -64,14 +87,19 @@ function Binder.new(tagName, constructor, ...)
 	return self
 end
 
---- Retrieves whether or not its a binder
--- @param value
--- @return true or false, whether or not it is a value
+--[=[
+	Retrieves whether or not the given value is a binder.
+
+	@param value any
+	@return boolean true or false, whether or not it is a value
+]=]
 function Binder.isBinder(value)
 	return type(value) == "table" and value.ClassName == "Binder"
 end
 
---- Listens for new instances and connects to the GetInstanceAddedSignal() and removed signal!
+--[=[
+	Listens for new instances and connects to the GetInstanceAddedSignal() and removed signal!
+]=]
 function Binder:Start()
 	if self._loaded then
 		return
@@ -90,17 +118,31 @@ function Binder:Start()
 	end))
 end
 
--- Returns the tag name that the binder has
+--[=[
+	Returns the tag name that the binder has.
+	@return string
+]=]
 function Binder:GetTag()
 	return self._tagName
 end
 
---- Returns whatever was set for the construtor. Used for meta-analysis of the binder, such as extracting new
+--[=[
+	Returns whatever was set for the construtor. Used for meta-analysis of
+	the binder, such as extracting if parameters are allowed.
+
+	@return BinderContructor
+]=]
 function Binder:GetConstructor()
 	return self._constructor
 end
 
--- Fired when added, and then after removal, but before destroy!
+--[=[
+	Fired when added, and then after removal, but before destroy!
+
+	@param inst Instance
+	@param callback function
+	@return function -- Cleanup function
+]=]
 function Binder:ObserveInstance(inst, callback)
 	self._listeners[inst] = self._listeners[inst] or {}
 	self._listeners[inst][callback] = true
@@ -117,19 +159,22 @@ function Binder:ObserveInstance(inst, callback)
 	end
 end
 
--- Returns a new signal that will fire whenever a class is bound to the binder
---[[
-@usage
+--[=[
+	Returns a new signal that will fire whenever a class is bound to the binder
 
-local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
+	```lua
+	local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
 
-birdBinder:GetClassAddedSignal():Connect(function(bird)
-	bird:Squack() -- Make the bird squack when it's first spawned
-end)
+	birdBinder:GetClassAddedSignal():Connect(function(bird)
+		bird:Squack() -- Make the bird squack when it's first spawned
+	end)
 
--- Load all birds
-birdBinder:Start()
-]]
+	-- Load all birds
+	birdBinder:Start()
+	```
+
+	@return Signal<T>
+]=]
 function Binder:GetClassAddedSignal()
 	if self._classAddedSignal then
 		return self._classAddedSignal
@@ -140,7 +185,11 @@ function Binder:GetClassAddedSignal()
 	return self._classAddedSignal
 end
 
--- Returns a new signal that will fire whenever a class is removing from the binder
+--[=[
+	Returns a new signal that will fire whenever a class is removing from the binder.
+
+	@return Signal<T>
+	]=]
 function Binder:GetClassRemovingSignal()
 	if self._classRemovingSignal then
 		return self._classRemovingSignal
@@ -152,7 +201,11 @@ function Binder:GetClassRemovingSignal()
 	return self._classRemovingSignal
 end
 
--- Returns a new signal that will fire whenever a class is removed from the binder
+--[=[
+	Returns a new signal that will fire whenever a class is removed from the binder.
+
+	@return Signal<T>
+]=]
 function Binder:GetClassRemovedSignal()
 	if self._classRemovedSignal then
 		return self._classRemovedSignal
@@ -164,21 +217,24 @@ function Binder:GetClassRemovedSignal()
 	return self._classRemovedSignal
 end
 
---[[
-@usage
+--[=[
+	Returns all of the classes in a new table.
 
-local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
+	```lua
+	local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
 
--- Update every bird every frame
-RunService.Stepped:Connect(function()
-	for _, bird in pairs(birdBinder:GetAll()) do
-		bird:Update()
-	end
-end)
+	-- Update every bird every frame
+	RunService.Stepped:Connect(function()
+		for _, bird in pairs(birdBinder:GetAll()) do
+			bird:Update()
+		end
+	end)
+
+	birdBinder:Start()
+	```
 
-birdBinder:Start()
-]]
---- Returns all of the classes in a new table
+	@return {T}
+]=]
 function Binder:GetAll()
 	local all = {}
 	for class, _ in pairs(self._allClassSet) do
@@ -188,30 +244,45 @@ function Binder:GetAll()
 end
 
 
---[[
-@usage
+--[=[
+	Faster method to get all items in a binder
 
-local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
+	```lua
+	local birdBinder = Binder.new("Bird", require("Bird")) -- Load bird into binder
 
--- Update every bird every frame
-RunService.Stepped:Connect(function()
-	for bird, _ in pairs(birdBinder:GetAllSet()) do
-		bird:Update()
-	end
-end)
+	-- Update every bird every frame
+	RunService.Stepped:Connect(function()
+		for bird, _ in pairs(birdBinder:GetAllSet()) do
+			bird:Update()
+		end
+	end)
 
-birdBinder:Start()
-]]
---- Faster method to get all items in a binder
--- NOTE: Do not mutate this set directly
+	birdBinder:Start()
+	```
+
+	:::warning
+	Do not mutate this set directly
+	:::
+
+	@return { [T]: boolean }
+]=]
 function Binder:GetAllSet()
 	return self._allClassSet
 end
 
---- Binds an instance to this binder using collection service and attempts
--- to return it if it's bound properly. See BinderUtils.promiseBoundClass() for a safe
--- way to retrieve it.
--- NOTE: Do not assume that a bound object will be retrieved
+--[=[
+	Binds an instance to this binder using collection service and attempts
+	to return it if it's bound properly. See BinderUtils.promiseBoundClass() for a safe
+	way to retrieve it.
+
+	:::warning
+	Do not assume that a bound object will be retrieved
+	:::
+
+	@server
+	@param inst Instance -- Instance to check
+	@return T? -- Bound class
+]=]
 function Binder:Bind(inst)
 	if RunService:IsClient() then
 		warn(("[Binder.Bind] - Bindings '%s' done on the client! Will be disrupted upon server replication! %s")
@@ -222,7 +293,12 @@ function Binder:Bind(inst)
 	return self:Get(inst)
 end
 
--- Unbinds the instance by removing the tag
+--[=[
+	Unbinds the instance by removing the tag.
+
+	@server
+	@param inst Instance -- Instance to unbind
+]=]
 function Binder:Unbind(inst)
 	assert(typeof(inst) == "Instance", "Bad inst'")
 
@@ -234,9 +310,16 @@ function Binder:Unbind(inst)
 	CollectionService:RemoveTag(inst, self._tagName)
 end
 
--- See :Bind(). Acknowledges the risk of doing this on the client.
--- Using this acknowledges that we're intentionally binding on a safe client object,
--- i.e. one without replication. If another tag is changed on this instance, this tag will be lost/changed.
+--[=[
+ See :Bind(). Acknowledges the risk of doing this on the client.
+
+ Using this acknowledges that we're intentionally binding on a safe client object,
+ i.e. one without replication. If another tag is changed on this instance, this tag will be lost/changed.
+
+ @client
+ @param inst Instance -- Instance to bind
+ @return T? -- Bound class (potentially)
+]=]
 function Binder:BindClient(inst)
 	if not RunService:IsClient() then
 		warn(("[Binder.BindClient] - Bindings '%s' done on the server! Will be replicated!")
@@ -247,18 +330,35 @@ function Binder:BindClient(inst)
 	return self:Get(inst)
 end
 
--- See Unbind(), acknowledges risk of doing this on the client.
+--[=[
+	See Unbind(), acknowledges risk of doing this on the client.
+
+	@client
+	@param inst Instance -- Instance to unbind
+]=]
 function Binder:UnbindClient(inst)
 	assert(typeof(inst) == "Instance", "Bad inst")
 	CollectionService:RemoveTag(inst, self._tagName)
 end
 
---- Returns a version of the clas
+--[=[
+	Returns a instance of the class that is bound to the instance given.
+
+	@param inst Instance -- Instance to check
+	@return T?
+]=]
 function Binder:Get(inst)
 	assert(typeof(inst) == "Instance", "Argument 'inst' is not an Instance")
 	return self._instToClass[inst]
 end
 
+--[=[
+	Returns a promise which will resolve when the instance is bound.
+
+	@param inst Instance -- Instance to check
+	@param cancelToken? CancelToken
+	@return Promise<T>
+]=]
 function Binder:Promise(inst, cancelToken)
 	assert(typeof(inst) == "Instance", "Argument 'inst' is not an Instance")
 	return promiseBoundClass(self, inst, cancelToken)
@@ -355,7 +455,9 @@ function Binder:_remove(inst)
 	end
 end
 
---- Cleans up all bound classes, and disconnects all events
+--[=[
+	Cleans up all bound classes, and disconnects all events.
+]=]
 function Binder:Destroy()
 	local inst, class = next(self._instToClass)
 	while class ~= nil do

package/src/Shared/BinderGroup.lua

@@ -1,5 +1,13 @@
---- Groups binders together
--- @classmod BinderGroup
+--[=[
+	Groups binders together into a list, and allows binders to be dynamically
+	added or removed.
+
+	Also allows their interface to be validated using a validation function.
+	This ensures that all added objects are the same type, so they can be used
+	for dynamic interactions.
+
+	@class BinderGroup
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,6 +18,13 @@ local BinderGroup = {}
 BinderGroup.ClassName = "BinderGroup"
 BinderGroup.__index = BinderGroup
 
+--[=[
+	Constructs a new BinderGroup
+
+	@param binders { Binder<T> } -- A list of binders that
+	@param validateConstructor (constructor: any) -> boolean -- Validates a binder matches T
+	@return BinderGroup<T>
+]=]
 function BinderGroup.new(binders, validateConstructor)
 	local self = setmetatable({}, BinderGroup)
 
@@ -24,6 +39,11 @@ function BinderGroup.new(binders, validateConstructor)
 	return self
 end
 
+--[=[
+	Adds a list of binders to the group.
+
+	@param binders { Binder<T> }
+]=]
 function BinderGroup:AddList(binders)
 	assert(type(binders) == "table", "Bad binders")
 
@@ -34,6 +54,11 @@ function BinderGroup:AddList(binders)
 	end
 end
 
+--[=[
+	Adds the specific binder to the list
+
+	@param binder Binder<T>
+]=]
 function BinderGroup:Add(binder)
 	assert(Binder.isBinder(binder))
 
@@ -52,6 +77,15 @@ function BinderGroup:Add(binder)
 	self.BinderAdded:Fire(binder)
 end
 
+--[=[
+	Returns a list of binders.
+
+	:::warning
+	Do not modify the list of binders returned here
+	:::
+
+	@return { T }
+]=]
 function BinderGroup:GetBinders()
 	assert(self._binders, "No self._binders")
 

package/src/Shared/BinderGroupProvider.lua

@@ -1,5 +1,7 @@
---- Provides a basis for binderGroups that can be retrieved anywhere
--- @classmod BinderGroupProvider
+--[=[
+	Provides a basis for binderGroups that can be retrieved anywhere
+	@class BinderGroupProvider
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,6 +11,11 @@ local BinderGroupProvider = {}
 BinderGroupProvider.ClassName = "BinderGroupProvider"
 BinderGroupProvider.__index = BinderGroupProvider
 
+--[=[
+	Constructs a new BinderGroupProvider
+	@param initMethod (BinderGroupProvider) -> ()
+	@return BinderGroupProvider
+]=]
 function BinderGroupProvider.new(initMethod)
 	local self = setmetatable({}, BinderGroupProvider)
 
@@ -21,10 +28,18 @@ function BinderGroupProvider.new(initMethod)
 	return self
 end
 
+--[=[
+	Returns a promise that will resolve once groups are added.
+	@return Promise
+]=]
 function BinderGroupProvider:PromiseGroupsAdded()
 	return self._groupsAddedPromise
 end
 
+--[=[
+	Starts the binder provider. Should be called via ServiceBag.
+	@param ... ServiceBag | any
+]=]
 function BinderGroupProvider:Init(...)
 	assert(not self._init, "Already initialized")
 
@@ -34,6 +49,9 @@ function BinderGroupProvider:Init(...)
 	self._groupsAddedPromise:Resolve()
 end
 
+--[=[
+	Starts the binder provider. Should be called via ServiceBag.
+]=]
 function BinderGroupProvider:Start()
 	-- Do nothing
 end
@@ -46,11 +64,23 @@ function BinderGroupProvider:__index(index)
 	error(("%q Not a valid index"):format(tostring(index)))
 end
 
-function BinderGroupProvider:Get(tagName)
-	assert(type(tagName) == "string", "tagName must be a string")
-	return rawget(self, tagName)
+--[=[
+	Returns a binder group given the binderName
+
+	@param groupName string
+	@return BinderGroup?
+]=]
+function BinderGroupProvider:Get(groupName)
+	assert(type(groupName) == "string", "groupName must be a string")
+	return rawget(self, groupName)
 end
 
+--[=[
+	Adds a new group at the given name
+
+	@param groupName string
+	@param binderGroup BinderGroup
+]=]
 function BinderGroupProvider:Add(groupName, binderGroup)
 	assert(type(groupName) == "string", "Bad groupName")
 	assert(type(binderGroup) == "table", "Bad binderGroup")

package/src/Shared/BinderProvider.lua

@@ -1,5 +1,7 @@
---- Provides a basis for binders that can be retrieved anywhere
--- @classmod BinderProvider
+--[=[
+	Provides a basis for binders that can be retrieved anywhere
+	@class BinderProvider
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,6 +11,28 @@ local BinderProvider = {}
 BinderProvider.ClassName = "BinderProvider"
 BinderProvider.__index = BinderProvider
 
+--[=[
+	Constructs a new BinderProvider.
+
+	```lua
+	local serviceBag = ServiceBag.new()
+
+	-- Usually in a separate file!
+	local binderProvider = BinderProvider.new(function(self, serviceBag)
+		serviceBag:Add(Binder.new("Bird", require("Bird")))
+	end)
+
+	-- Retrieve binders
+	local binders = serviceBag:GetService(binderProvider)
+
+	-- Runs the game (including binders)
+	serviceBag:Init()
+	serviceBag:Start()
+	```
+
+	@param initMethod (self, serviceBag: ServiceBag)
+	@return BinderProvider
+]=]
 function BinderProvider.new(initMethod)
 	local self = setmetatable({}, BinderProvider)
 
@@ -25,13 +49,21 @@ function BinderProvider.new(initMethod)
 	return self
 end
 
---- Retrieves whether or not its a binder provider
--- @param value
--- @return true or false, whether or not it is a value
+--[=[
+	Retrieves whether or not its a binder provider
+	@param value any
+	@return boolean -- True if it is a binder provider
+]=]
 function BinderProvider.isBinderProvider(value)
 	return type(value) == "table" and value.ClassName == "BinderProvider"
 end
 
+--[=[
+	Resolves to the given binder given the binderName.
+
+	@param binderName string
+	@return Promise<Binder<T>>
+]=]
 function BinderProvider:PromiseBinder(binderName)
 	if self._bindersAddedPromise:IsFulfilled() then
 		local binder = self:Get(binderName)
@@ -53,7 +85,11 @@ function BinderProvider:PromiseBinder(binderName)
 		end)
 end
 
--- Initializes itself and all binders
+--[=[
+	Initializes itself and all binders
+
+	@param ... ServiceBag | any
+]=]
 function BinderProvider:Init(...)
 	assert(not self._initialized, "Already initialized")
 
@@ -62,15 +98,27 @@ function BinderProvider:Init(...)
 	self._bindersAddedPromise:Resolve()
 end
 
+--[=[
+	Returns a promise that will resolve once all binders are added.
+
+	@return Promise
+]=]
 function BinderProvider:PromiseBindersAdded()
 	return self._bindersAddedPromise
 end
 
+--[=[
+	Returns a promise that will resolve once all binders are started.
+
+	@return Promise
+]=]
 function BinderProvider:PromiseBindersStarted()
 	return self._startPromise
 end
 
--- Starts all of the binders
+--[=[
+	Starts all of the binders.
+]=]
 function BinderProvider:Start()
 	assert(self._initialized, "Not initialized")
 	assert(not self._started, "Already started")
@@ -92,11 +140,22 @@ function BinderProvider:__index(index)
 	error(("%q Not a valid index"):format(tostring(index)))
 end
 
+--[=[
+	Retrieves a binder given a tagName
+
+	@param tagName string
+	@return Binder<T>?
+]=]
 function BinderProvider:Get(tagName)
 	assert(type(tagName) == "string", "tagName must be a string")
 	return rawget(self, tagName)
 end
 
+--[=[
+	Adds a binder given a tag name.
+
+	@param binder Binder<T>
+]=]
 function BinderProvider:Add(binder)
 	assert(not self._started, "Already inited")
 	assert(not self:Get(binder:GetTag()), "Binder already exists")

package/src/Shared/BinderUtils.lua

@@ -1,10 +1,20 @@
---- Utility methods for binders
--- @module BinderUtils
+--[=[
+	Utility methods for the binder object.
+	@class BinderUtils
+]=]
 
 local CollectionService = game:GetService("CollectionService")
 
 local BinderUtils = {}
 
+--[=[
+	Finds the first ancestor that is bound with the current child.
+	Skips the child class, of course.
+
+	@param binder Binder<T>
+	@param child Instance
+	@return T?
+]=]
 function BinderUtils.findFirstAncestor(binder, child)
 	assert(type(binder) == "table", "Binder must be binder")
 	assert(typeof(child) == "Instance", "Child parameter must be instance")
@@ -20,6 +30,14 @@ function BinderUtils.findFirstAncestor(binder, child)
 	return nil
 end
 
+--[=[
+	Finds the first child bound with the given binder and returns
+	the bound class.
+
+	@param binder Binder<T>
+	@param parent Instance
+	@return T?
+]=]
 function BinderUtils.findFirstChild(binder, parent)
 	assert(type(binder) == "table", "Binder must be binder")
 	assert(typeof(parent) == "Instance", "Parent parameter must be instance")
@@ -34,6 +52,13 @@ function BinderUtils.findFirstChild(binder, parent)
 	return nil
 end
 
+--[=[
+	Gets all bound children of the given binder for the parent.
+
+	@param binder Binder<T>
+	@param parent Instance
+	@return {T}
+]=]
 function BinderUtils.getChildren(binder, parent)
 	assert(type(binder) == "table", "Binder must be binder")
 	assert(typeof(parent) == "Instance", "Parent parameter must be instance")
@@ -48,6 +73,16 @@ function BinderUtils.getChildren(binder, parent)
 	return objects
 end
 
+
+--[=[
+	Maps a list of binders into a look up table where the keys are
+	tags and the value is the binder.
+
+	Duplicates are overwritten by the last entry.
+
+	@param bindersList { Binder<any> }
+	@return { [string]: Binder<any> }
+]=]
 function BinderUtils.mapBinderListToTable(bindersList)
 	assert(type(bindersList) == "table", "bindersList must be a table of binders")
 
@@ -58,6 +93,19 @@ function BinderUtils.mapBinderListToTable(bindersList)
 	return tags
 end
 
+--[=[
+	Given a mapping of tags to binders, retrieves the bound values
+	from an instanceList by quering the list of :GetTags() instead
+	of iterating over each binder.
+
+	This lookup should be faster when there are potentially many
+	interaction points for a given tag map, but the actual bound
+	list should be low.
+
+	@param tagsMap { [string]: Binder<T> }
+	@param instanceList { Instance }
+	@return { T }
+]=]
 function BinderUtils.getMappedFromList(tagsMap, instanceList)
 	local objects = {}
 
@@ -76,6 +124,13 @@ function BinderUtils.getMappedFromList(tagsMap, instanceList)
 	return objects
 end
 
+--[=[
+	Given a list of binders retrieves all children bound with the given value.
+
+	@param bindersList { Binder<T> }
+	@param parent Instance
+	@return { T }
+]=]
 function BinderUtils.getChildrenOfBinders(bindersList, parent)
 	assert(type(bindersList) == "table", "bindersList must be a table of binders")
 	assert(typeof(parent) == "Instance", "Parent parameter must be instance")
@@ -84,6 +139,14 @@ function BinderUtils.getChildrenOfBinders(bindersList, parent)
 	return BinderUtils.getMappedFromList(tagsMap, parent:GetChildren())
 end
 
+--[=[
+	Gets all the linked (via objectValues of name `linkName`) bound objects
+
+	@param binder Binder<T>
+	@param linkName string -- Name of the object values required
+	@param parent Instance
+	@return {T}
+]=]
 function BinderUtils.getLinkedChildren(binder, linkName, parent)
 	local seen = {}
 	local objects = {}
@@ -103,6 +166,13 @@ function BinderUtils.getLinkedChildren(binder, linkName, parent)
 	return objects
 end
 
+--[=[
+	Gets all bound descendants of the given binder for the parent.
+
+	@param binder Binder<T>
+	@param parent Instance
+	@return {T}
+]=]
 function BinderUtils.getDescendants(binder, parent)
 	assert(type(binder) == "table", "Binder must be binder")
 	assert(typeof(parent) == "Instance", "Parent parameter must be instance")

package/src/Shared/Collection/BoundChildCollection.lua

@@ -1,5 +1,7 @@
---- Tracks child of type
--- @classmod BoundChildCollection
+--[=[
+	Tracks child of type of a binder.
+	@class BoundChildCollection
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,17 +12,31 @@ local BoundChildCollection = setmetatable({}, BaseObject)
 BoundChildCollection.ClassName = "BoundChildCollection"
 BoundChildCollection.__index = BoundChildCollection
 
+--[=[
+	Constructcs a new BoundChildCollection.
+	@param binder Binder<T>
+	@param parent Instance
+	@return BoundChildCollection<T>
+]=]
 function BoundChildCollection.new(binder, parent)
 	local self = setmetatable(BaseObject.new(), BoundChildCollection)
 
 	self._binder = binder or error("No binder")
 	self._parent = parent or error("No parent")
 
-	--- Fires on class addition
+--[=[
+	Fires on class addition
+	@prop ClassAdded Signal<T>
+	@within BoundChildCollection
+]=]
 	self.ClassAdded = Signal.new() -- :Fire(class)
 	self._maid:GiveTask(self.ClassAdded)
 
-	--- Fires on class removal
+--[=[
+	Fires on class removal
+	@prop ClassRemoved Signal<T>
+	@within BoundChildCollection
+]=]
 	self.ClassRemoved = Signal.new() -- :Fire(class)
 	self._maid:GiveTask(self.ClassRemoved)
 
@@ -39,24 +55,40 @@ function BoundChildCollection.new(binder, parent)
 	return self
 end
 
---- Returns whether the track has the class
--- @return true if the class exists, nil otherwise
+--[=[
+	Returns whether the track has the class
+	@param class T
+	@return boolean? -- true if the class exists, nil otherwise
+]=]
 function BoundChildCollection:HasClass(class)
 	return self._classes[class]
 end
 
+--[=[
+	Gets the size
+	@return number
+]=]
 function BoundChildCollection:GetSize()
 	return self._size
 end
 
---- Returns the raw classes variable as [class] = true
--- @return The set
+--[=[
+	Returns the raw classes variable as [class] = true.
+
+	:::warning
+	Do not modify the set
+	:::
+
+	@return { [T] = true } -- The set
+]=]
 function BoundChildCollection:GetSet()
 	return self._classes
 end
 
---- Slow than :GetSet(), but adds them in an ordered list
--- @return The list
+--[=[
+	Slow than :GetSet(), but adds them in an ordered list
+	@return { T }
+]=]
 function BoundChildCollection:GetClasses()
 	local list = {}
 	for class, _ in pairs(self._classes) do

package/src/Shared/Promise/promiseBoundClass.lua

@@ -1,11 +1,22 @@
---- Utility function to promise a bound class on an object
--- @function promiseBoundClass
+--[=[
+	Utility function to promise a bound class on an object
+	@class promiseBoundClass
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
 local Promise = require("Promise")
 local Maid = require("Maid")
 
+--[=[
+Returns a promise that resolves when the class is bound to the instance.
+@param binder Binder<T>
+@param inst Instance
+@param cancelToken CancelToken
+@return Promise<T>
+@function promiseBoundClass
+@within promiseBoundClass
+]=]
 return function(binder, inst, cancelToken)
 	assert(type(binder) == "table", "'binder' must be table")
 	assert(typeof(inst) == "Instance", "'inst' must be instance")

package/src/Shared/Trackers/BoundAncestorTracker.lua

@@ -1,5 +1,7 @@
---- Tracks a parent bound to a specific binder
--- @classmod BoundAncestorTracker
+--[=[
+	Tracks a parent bound to a specific binder
+	@class BoundAncestorTracker
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -11,13 +13,26 @@ local BoundAncestorTracker = setmetatable({}, BaseObject)
 BoundAncestorTracker.ClassName = "BoundAncestorTracker"
 BoundAncestorTracker.__index = BoundAncestorTracker
 
+
+--[=[
+Constructs a new BoundAncestorTracker
+
+@param binder Binder<T>
+@param child Instance
+@return BoundAncestorTracker
+]=]
 function BoundAncestorTracker.new(binder, child)
 	local self = setmetatable(BaseObject.new(), BoundAncestorTracker)
 
 	self._child = child or error("No child")
 	self._binder = binder or error("No binder")
 
-	-- Bound value
+--[=[
+	@prop Class ValueObject<T>
+	@readonly
+	@within BoundAncestorTracker
+	Bound value
+]=]
 	self.Class = ValueObject.new()
 	self._maid:GiveTask(self.Class)
 

package/src/Shared/Trackers/BoundParentTracker.lua

@@ -1,5 +1,7 @@
---- Tracks a parent bound to a specific binder
--- @classmod BoundParentTracker
+--[=[
+	Tracks a parent bound to a specific binder
+	@class BoundParentTracker
+]=]
 
 local require = require(script.Parent.loader).load(script)