Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feature/eng 157: Write moonwave documentation for Metrik API #32

Open
wants to merge 1 commit into
base: development
Choose a base branch
from
Open

feature/eng 157: Write moonwave documentation for Metrik API #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 91 additions & 5 deletions Src/API/ActionBuilder.luau
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@ local Sift = require(script.Parent.Parent.Packages.Sift)

local ActionService = require(script.Parent.Parent.Services.ActionService)

--[[
Metrik SDK ActionBuilder & Action
]]

--[=[
@class ActionBuilder

Expand All @@ -31,14 +27,36 @@ Action.Prototype = {}
ActionBuilder.Public = {}
ActionBuilder.Prototype = {}

--[=[
CanRun is called when the Action is run, this method is used to determine if the Action can be run.

@method CanRun
@within Action
@return boolean
]=]
function Action.Prototype:CanRun(...: unknown)
return true
end

--[=[
OnRun is called when the Action is run, this method is used to execute the Action.

@method OnRun
@within Action
@return boolean
]=]
function Action.Prototype:OnRun(...: unknown)
print(`Method ':OnRun' has been called on Action<"{self.Name}">`)
end

--[=[
SetName is used to set the name of the Action.

@method SetName
@param actionName string
@within ActionBuilder
@return ActionBuilder
]=]
function ActionBuilder.Prototype.SetName(self: ActionBuilder, actionName: string): ActionBuilder
assert(#actionName <= 50, `Action name is too large, action name ranges between 1 <-> 50 characters!`)

Expand All @@ -54,6 +72,14 @@ function ActionBuilder.Prototype.SetName(self: ActionBuilder, actionName: string
return self
end

--[=[
SetDescription is used to set the description of the Action.

@method SetDescription
@param description string
@within ActionBuilder
@return ActionBuilder
]=]
function ActionBuilder.Prototype.SetDescription(self: ActionBuilder, description: string): ActionBuilder
assert(string.len(description) <= 500, "Action Description must be under 500 characters!")

Expand All @@ -62,18 +88,49 @@ function ActionBuilder.Prototype.SetDescription(self: ActionBuilder, description
return self
end

--[=[
OnRun is used to set the callback that is called when the Action is run.

@method OnRun
@param callback (Action, ...any) -> ...any
@within ActionBuilder
@return ActionBuilder
]=]
function ActionBuilder.Prototype.OnRun(self: ActionBuilder, callback: (Action, ...any) -> ...any): ActionBuilder
self.Prototype.OnRun = callback

return self
end

function ActionBuilder.Prototype.CanRun(self: ActionBuilder, callback: (Action, ...any) -> ...any): ActionBuilder
--[=[
CanRun is used to set the callback that is called when the Action can be run.

@method CanRun
@param callback (Action, ...any) -> boolean
@within ActionBuilder
@return ActionBuilder
]=]
function ActionBuilder.Prototype.CanRun(self: ActionBuilder, callback: (Action, ...any) -> boolean): ActionBuilder
self.Prototype.CanRun = callback

return self
end

--[=[
AddArgument is used to add an argument to the Action.

@method AddArgument
@param argumentName string
@param argumentMetadata {
Type: ("string" | "number" | "boolean")?,
Description: string?,
Required: boolean?,
IsArray: boolean?,
Default: any,
}?
@within ActionBuilder
@return ActionBuilder
]=]
function ActionBuilder.Prototype.AddArgument(self: ActionBuilder, argumentName: string, argumentMetadata: ArgumentMetadata?): ActionBuilder
local filteredArgumentName = string.lower(argumentName)
local argumentsDict = self.Prototype.Arguments :: { }
Expand All @@ -95,6 +152,21 @@ function ActionBuilder.Prototype.AddArgument(self: ActionBuilder, argumentName:
return self
end

--[=[
AddArguments is used to add multiple arguments to the Action.

@method AddArguments
@param arguments {
[string]: {
Type: ("string" | "number" | "boolean")?,
Description: string?,
Required: boolean?,
Default: any,
}
}
@within ActionBuilder
@return ActionBuilder
]=]
function ActionBuilder.Prototype.AddArguments(self: ActionBuilder, arguments: {
[string]: {
Type: ("string" | "number" | "boolean")?,
Expand All @@ -115,6 +187,13 @@ function ActionBuilder.Prototype.AddArguments(self: ActionBuilder, arguments: {
return self
end

--[=[
Build is used to build the Action.

@method Build
@within ActionBuilder
@return Action
]=]
function ActionBuilder.Prototype.Build(self: ActionBuilder): Action
assert(self.Prototype.Name ~= nil, "Actions are required to have a 'Name', please call ':SetName'")
assert(Action.Instantiated[self.Prototype.Key] == nil, `Action '{self.Prototype.Name}' is a duplicate action!`)
Expand All @@ -133,6 +212,13 @@ function ActionBuilder.Prototype.Build(self: ActionBuilder): Action
return Action.Instantiated[self.Prototype.Key]
end

--[=[
Creates a new ActionBuilder.

@function new
@within ActionBuilder
@return ActionBuilder
]=]
function ActionBuilder.Public.new(): ActionBuilder
return setmetatable({
Prototype = {
Expand Down
27 changes: 12 additions & 15 deletions Src/Client.luau
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ local ON_START_LIFECYCLE_NAME = "OnStart"
--[=[
@class MetrikSDK.Client

The base class developers will be interacting with. *(TO-DO: add a descriptive class description!)*
The MetrikSDK.Client class is the main entry point for interacting with the Metrik Service on the Client.
]=]
local MetrikSDK = {}

Expand All @@ -41,9 +41,10 @@ function MetrikSDK.Private.AwaitUntilReady(self: MetrikPrivateAPI)
end

--[=[
...
Defer to @MetrikSDK.CreateBreadcrumb

@method CreateBreadcrumb
@param message string
@within MetrikSDK.Client

@return ()
Expand All @@ -56,9 +57,10 @@ function MetrikSDK.Public.CreateBreadcrumb(self: MetrikPublicAPI, message: strin
end

--[=[
...
Defer to @MetrikSDK.SetContext

@method SetContext
@param context { [string]: any }
@within MetrikSDK.Client

@return ()
Expand All @@ -71,12 +73,13 @@ function MetrikSDK.Public.SetContext(self: MetrikPublicAPI, context: { [string]:
end

--[=[
...
Defer to @MetrikSDK.GetFlag

@method EvaluateFlag
@within MetrikSDK.Server
@method GetFlag
@param context { [string]: any }
@within MetrikSDK.Client

@return ()
@return boolean
]=]
--
function MetrikSDK.Public.GetFlag(self: MetrikPublicAPI, flagName: string)
Expand All @@ -86,16 +89,10 @@ function MetrikSDK.Public.GetFlag(self: MetrikPublicAPI, flagName: string)
end

--[=[
Start the Metrik SDK, once this function has been called, internal Metrik Services and Controllers should come online and start to respond and
handle Metrik backend calls made to the current Roblox server.

:::warning
Please ensure that any pre-init variables are set before calling this function, otherwise Metrik will have issues attempting to authenticate
the current SDK!
:::
Defer to @MetrikSDK.InitializeAsync

@method InitializeAsync
@within MetrikSDK
@within MetrikSDK.Client

@return Promise<()>
]=]
Expand Down
41 changes: 20 additions & 21 deletions Src/Server.luau
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ local ON_START_LIFECYCLE_NAME = "OnStart"
--[=[
@class MetrikSDK.Server

The base class developers will be interacting with. *(TO-DO: add a descriptive class description!)*
The MetrikSDK.Server class is the main entry point for interacting with the Metrik Service on the Server.
]=]
local MetrikSDK = {}

Expand All @@ -46,7 +46,12 @@ MetrikSDK.Private.ProjectId = ""
@prop ActionBuilder ActionBuilder
@within MetrikSDK.Server
]=]
--

--[=[
@prop ActionBuilder ActionBuilder
@within MetrikSDK.Server
]=]

MetrikSDK.Public.ActionBuilder = ActionBuilder

function MetrikSDK.Private.FromError(_: MetrikPrivateAPI, errorEnum: string, ...: string)
Expand Down Expand Up @@ -78,38 +83,39 @@ function MetrikSDK.Private.GetCallingScript(_: MetrikPrivateAPI)
end

--[=[
...
Defer to @MetrikSDK.CreateBreadcrumb

@method CreateBreadcrumb
@param message string
@within MetrikSDK.Server

@return ()
]=]
--
function MetrikSDK.Public.CreateBreadcrumb(self: MetrikPublicAPI, message: string)
BreadcrumbService:CreateBreadcrumbFor(nil, self.Private:GetCallingScript(), message)
end

--[=[
...
Defer to @MetrikSDK.SetContext

@method SetContext
@param context { [string]: any }
@within MetrikSDK.Server

@return ()
]=]
--
function MetrikSDK.Public.SetContext(self: MetrikPublicAPI, context: { [string]: any })
ContextService:CreateContextFor(nil, self.Private:GetCallingScript(), context)
end

--[=[
Defer to @MetrikSDK.IsServerUpToDate

@method IsServerUpToDate
@within MetrikSDK.Server

@return ()
@return boolean
]=]
--
function MetrikSDK.Public.IsServerUpToDate(self: MetrikPublicAPI)
local success, response = ApiService:GetAsync(string.format(ApiPaths.GetLatestPlaceVersion, ApiService.ProjectId), { }):await()

Expand All @@ -125,34 +131,27 @@ function MetrikSDK.Public.IsServerUpToDate(self: MetrikPublicAPI)
end

--[=[
...
Defer to @MetrikSDK.GetFlag

@method EvaluateFlag
@method GetFlag
@param flagName string
@within MetrikSDK.Server

@return ()
@return boolean
]=]
--
function MetrikSDK.Public.GetFlag(self: MetrikPublicAPI, flagName: string)
return FlagsService:EvaluateFlag(flagName)
end

--[=[
Start the Metrik SDK, once this function has been called, internal Metrik Services and Controllers should come online and start to respond and
handle Metrik backend calls made to the current Roblox server.

:::warning
Please ensure that any pre-init variables are set before calling this function, otherwise Metrik will have issues attempting to authenticate
the current SDK!
:::
Defer to @MetrikSDK.InitializeAsync

@method InitializeAsync
@param settings { projectId: string, authenticationSecret: Secret }
@within MetrikSDK.Server
@within MetrikSDK.Client

@return Promise<()>
]=]
--
function MetrikSDK.Public.InitializeAsync(self: MetrikPublicAPI, settings: {
projectId: string,
authenticationSecret: Secret
Expand Down
Loading