From bcf84d058c5930adbbf43ccc57e8298feafdcbf1 Mon Sep 17 00:00:00 2001 From: Elttob Date: Tue, 31 Jan 2023 03:36:28 +0000 Subject: [PATCH] API Reference completeness --- docs/api-reference/animation/spring.md | 12 ++--- docs/api-reference/instances/child.md | 2 +- docs/api-reference/instances/cleanup.md | 50 ++++++++++++++++++++ docs/api-reference/instances/specialkey.md | 4 +- docs/api-reference/state/cleanup.md | 53 ++++++++++++++++++++++ docs/api-reference/state/computed.md | 4 +- docs/api-reference/state/doNothing.md | 36 +++++++++++++++ mkdocs.yml | 2 + 8 files changed, 152 insertions(+), 11 deletions(-) create mode 100644 docs/api-reference/instances/cleanup.md create mode 100644 docs/api-reference/state/cleanup.md create mode 100644 docs/api-reference/state/doNothing.md diff --git a/docs/api-reference/animation/spring.md b/docs/api-reference/animation/spring.md index 7718f2e1e..9b871c8b0 100644 --- a/docs/api-reference/animation/spring.md +++ b/docs/api-reference/animation/spring.md @@ -71,8 +71,8 @@ captured. Instantaneously moves the spring to a new position. This does not affect the velocity of the spring. -If the given value doesn't have the same type as the spring's current value, an -error will be thrown. +If the given value doesn't have the same type as the spring's current value, +the position will snap instantly to the new value. ```Lua (newPosition: T) -> () @@ -93,8 +93,8 @@ error will be thrown. Overwrites the velocity of this spring. This does not have an immediate effect on the position of the spring. -If the given value doesn't have the same type as the spring's current value, an -error will be thrown. +If the given value doesn't have the same type as the spring's current value, +the velocity will snap instantly to the new value. ```Lua (newVelocity: T) -> () @@ -115,8 +115,8 @@ error will be thrown. Adds to the velocity of this spring. This does not have an immediate effect on the position of the spring. -If the given value doesn't have the same type as the spring's current value, an -error will be thrown. +If the given value doesn't have the same type as the spring's current value, +the velocity will snap instantly to the new value. ```Lua (deltaVelocity: T) -> () diff --git a/docs/api-reference/instances/child.md b/docs/api-reference/instances/child.md index 27a57da87..db1a358f7 100644 --- a/docs/api-reference/instances/child.md +++ b/docs/api-reference/instances/child.md @@ -18,7 +18,7 @@ to parent multiple instances at once and state objects can be used to make the children dynamic. ```Lua -Instance | {Child} | StateObject +Instance | {[any]: Child} | StateObject ``` ----- diff --git a/docs/api-reference/instances/cleanup.md b/docs/api-reference/instances/cleanup.md new file mode 100644 index 000000000..bb9182d96 --- /dev/null +++ b/docs/api-reference/instances/cleanup.md @@ -0,0 +1,50 @@ + + +

+ :octicons-key-24: + Cleanup + + special key + since v0.2 + +

+ +Cleans up all items given to it when the instance is destroyed, equivalent to +passing the items to `Fusion.cleanup`. + +----- + +## Example Usage + +```Lua +local example1 = New "Folder" { + [Cleanup] = function() + print("I'm in danger!") + end +} + +local example2 = New "Folder" { + [Cleanup] = example1 +} + +local example3 = New "Folder" { + [Cleanup] = { + RunService.RenderStepped:Connect(print), + function() + print("I'm in danger also!") + end, + example2 + } +} + +example3:Destroy() +``` + +----- + +## Technical Details + +This special key runs at the `observer` stage. \ No newline at end of file diff --git a/docs/api-reference/instances/specialkey.md b/docs/api-reference/instances/specialkey.md index d9fe28a8e..452d58238 100644 --- a/docs/api-reference/instances/specialkey.md +++ b/docs/api-reference/instances/specialkey.md @@ -24,7 +24,7 @@ instance processing. Compatible with the [New](./new.md) and apply: ( self: SpecialKey, value: any, - applyTo: SemiWeakRef, + applyTo: Instance, cleanupTasks: {Task} ) -> () } @@ -52,7 +52,7 @@ Example.kind = "Example" Example.stage = "observer" function Example:apply(value, applyTo, cleanupTasks) - local conn = applyTo.instance:GetAttributeChangedSignal("Foo"):Connect(function() + local conn = applyTo:GetAttributeChangedSignal("Foo"):Connect(function() print("My value is", value) end) table.insert(cleanupTasks, conn) diff --git a/docs/api-reference/state/cleanup.md b/docs/api-reference/state/cleanup.md new file mode 100644 index 000000000..ccde7d676 --- /dev/null +++ b/docs/api-reference/state/cleanup.md @@ -0,0 +1,53 @@ + + +

+ :octicons-code-24: + cleanup + + function + since v0.2 + +

+ +Attempts to destroy all destructible objects passed to it. + +```Lua +(...any) -> () +``` + +----- + +## Parameters + +- `...` - Any objects that need to be destroyed. + +----- + +## Example Usage + +```Lua +Fusion.cleanup( + workspace.Part1, + RunService.RenderStepped:Connect(print), + function() + print("I will be run!") + end +) +``` + +----- + +## Destruction Behaviour + +Destruction behaviour varies by type: + +- if `Instance`, `:Destroy()` is called +- ...else if `RBXScriptConnection`, `:Disconnect()` is called +- ...else if `function`, it is called +- ...else if `{destroy: (self) -> ()}`, `:destroy()` is called +- ...else if `{Destroy: (self) -> ()}`, `:Destroy()` is called +- ...else if `{any}`, `Fusion.cleanup` is called on all members +- ...else nothing occurs. \ No newline at end of file diff --git a/docs/api-reference/state/computed.md b/docs/api-reference/state/computed.md index 01128e35c..e68a7e6a6 100644 --- a/docs/api-reference/state/computed.md +++ b/docs/api-reference/state/computed.md @@ -25,10 +25,10 @@ Calculates a single value based on the returned values from other state objects. ## Parameters -- `processor: () -> (T, any?)` - computes and returns values to be returned from +- `processor: () -> (T, M)` - computes and returns values to be returned from the computed object, optionally returning extra values for the destructor alone -- `destructor: ((T, any?) -> ())?` - disposes of values generated by `processor` +- `destructor: ((T, M) -> ())?` - disposes of values generated by `processor` when they are no longer in use ----- diff --git a/docs/api-reference/state/doNothing.md b/docs/api-reference/state/doNothing.md new file mode 100644 index 000000000..f0de4865f --- /dev/null +++ b/docs/api-reference/state/doNothing.md @@ -0,0 +1,36 @@ + + +

+ :octicons-code-24: + doNothing + + function + since v0.2 + +

+ +No-op function - does nothing at all, and returns nothing at all. Intended for +use as a destructor when no destruction is needed. + +```Lua +(...any) -> () +``` + +----- + +## Parameters + +- `...` - Any objects. + +----- + +## Example Usage + +```Lua +local foo = Computed(function() + return workspace.Part +end, Fusion.doNothing) +``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index ac87f51ae..3a7f97060 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -100,8 +100,10 @@ nav: - api-reference/state/index.md - CanBeState: api-reference/state/canbestate.md - Computed: api-reference/state/computed.md + - cleanup: api-reference/state/cleanup.md - Dependency: api-reference/state/dependency.md - Dependent: api-reference/state/dependent.md + - doNothing: api-reference/state/doNothing.md - ForKeys: api-reference/state/forkeys.md - ForPairs: api-reference/state/forpairs.md - ForValues: api-reference/state/forvalues.md