From 64b55f92ef5d3bdfda17209d680d1d3ee46afe04 Mon Sep 17 00:00:00 2001
From: James <119134081+2jammers@users.noreply.github.com>
Date: Thu, 12 Sep 2024 21:47:15 -0500
Subject: [PATCH] adds api docs

---
 docs/changelog.md                  |  4 ++++
 src/Library/Action.luau            |  5 +++++
 src/Library/Data.luau              | 26 ++++++++++++++++++++++++++
 src/Library/Interface/Menu.luau    | 21 +++++++++++++++++++++
 src/Library/Interface/Toolbar.luau | 12 +++++++++++-
 wally.toml                         |  2 +-
 6 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/docs/changelog.md b/docs/changelog.md
index c87c3ab..5e514dc 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added API documentation to every function within the code
+
 ## [0.3.0] - 2024-09-12
 
 ### Added
diff --git a/src/Library/Action.luau b/src/Library/Action.luau
index 683c6ac..ac27585 100644
--- a/src/Library/Action.luau
+++ b/src/Library/Action.luau
@@ -5,6 +5,11 @@ local plugin: Plugin = script:FindFirstAncestorWhichIsA("Plugin")
 
 -- Functions
 
+--[=[
+	Creates a new plugin action that can be bound to a keycode or placed in studio's topbar.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/action#new)
+]=]
 local function New(
 	name: string,
 	description: string,
diff --git a/src/Library/Data.luau b/src/Library/Data.luau
index ccdd897..08c9543 100644
--- a/src/Library/Data.luau
+++ b/src/Library/Data.luau
@@ -5,6 +5,11 @@ local Cache = {}
 
 -- Functions
 
+--[=[
+	Gets the value of a key in the current session's cache or directly from the last save.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/data#set)
+]=]
 local function Get(key: string, useCache: boolean?): any
 	if useCache == false then
 		return plugin:GetSetting(key)
@@ -14,15 +19,30 @@ local function Get(key: string, useCache: boolean?): any
 	return Result
 end
 
+--[=[
+	Sets a key within the current session's cache to be saved on shutdown.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/data#set)
+]=]
 local function Set(key: string, value: any, ignoreCacheIndex: boolean?)
 	assert(ignoreCacheIndex == false and Cache[key], "No such key found in cache")
 	Cache[key] = value
 end
 
+--[=[
+	Saves a key to the user's local data directly without interacting with cache.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/data#save)
+]=]
 local function Save(key: string, value: any)
 	plugin:SetSetting(key, value)
 end
 
+--[=[
+	Removes a key from the user's local data.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/data#remove)
+]=]
 local function Remove(key: string, useCache: boolean?)
 	if useCache == false then
 		Save(key, nil)
@@ -31,6 +51,12 @@ local function Remove(key: string, useCache: boolean?)
 	Set(key, nil)
 end
 
+--[=[
+	Updates the value of a key using the current session's cache, uses a callback function
+    to calculate a new returned value.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/data#update)
+]=]
 local function Update(key: string, callback: (value: any) -> any, useCache: boolean?)
 	local Result = callback(Get(key))
 	assert(Result, "Must resolve a value in the update callback")
diff --git a/src/Library/Interface/Menu.luau b/src/Library/Interface/Menu.luau
index f4251a2..598df86 100644
--- a/src/Library/Interface/Menu.luau
+++ b/src/Library/Interface/Menu.luau
@@ -35,6 +35,11 @@ local function PluginMenu(name: string, children: Types.MenuChildren, icon: stri
 	return Menu
 end
 
+--[=[
+	Creates a new plugin menu that is visually similar to a context menu.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/menu#new)
+]=]
 local function New(name: string, children: Types.MenuChildren, icon: string?)
 	local self = setmetatable({
 		Menu = PluginMenu(name, children, icon or ""),
@@ -42,14 +47,30 @@ local function New(name: string, children: Types.MenuChildren, icon: string?)
 	return self
 end
 
+--[=[
+	Appends a new menu to the parent menu.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/menu#append)
+]=]
 function Index.Append(self: any, children: Types.MenuChildren)
 	self.Menu:AddMenu()
 end
 
+--[=[
+	Clears the menu, removing any items left inside.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/menu#clear)
+]=]
 function Index.Clear(self: any)
     self.Menu:Clear()
 end
 
+--[=[
+	Shows the menu, and runs the provided callback giving the chosen `PluginAction` as an
+    argument. The callback will not run if the user does not choose an option.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/menu#show)
+]=]
 function Index.Show(self: any, callback: (id: PluginAction) -> ())
     local Identifier = self.Menu:ShowAsync()
     if Identifier then
diff --git a/src/Library/Interface/Toolbar.luau b/src/Library/Interface/Toolbar.luau
index 9983f55..523bc4c 100644
--- a/src/Library/Interface/Toolbar.luau
+++ b/src/Library/Interface/Toolbar.luau
@@ -7,6 +7,11 @@ Index.__index = Index
 
 -- Functions
 
+--[=[
+	Creates a new plugin toolbar with a specified name.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/toolbar#new)
+]=]
 local function New(name: string)
 	local self = setmetatable({
 		Toolbar = plugin:CreateToolbar(name),
@@ -15,7 +20,12 @@ local function New(name: string)
 	return self
 end
 
-function Index.Button(self: any, name: string, tooltip: string, image: string, onClick: () -> ())
+--[=[
+	Creates a new toolbar button using the toolbar it was created on.
+
+	[Learn More](https://luminlabsdev.github.io/plugin-framework/api/toolbar#append)
+]=]
+function Index.Append(self: any, name: string, tooltip: string, image: string, onClick: () -> ())
 	local Button = self.Toolbar:CreateButton(name, tooltip, image)
     Button.Click:Connect(onClick)
     table.insert(self.Buttons, Button)
diff --git a/wally.toml b/wally.toml
index 301640a..4c6b49d 100644
--- a/wally.toml
+++ b/wally.toml
@@ -1,6 +1,6 @@
 [package]
 name = "lumin/plugin-framework"
-version = "0.3.0"
+version = "0.4.0"
 registry = "https://github.com/UpliftGames/wally-index"
 realm = "shared"