@quenty/steputils 3.0.1-canary.9c1fd3b.0 → 3.0.1

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [3.0.1-canary.9c1fd3b.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.0.0...@quenty/steputils@3.0.1-canary.9c1fd3b.0) (2021-09-11)
+## [3.0.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/steputils@3.0.0...@quenty/steputils@3.0.1) (2021-12-30)
 
 **Note:** Version bump only for package @quenty/steputils
 

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014 Quenty
+Copyright (c) 2014-2021 Quenty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
 ## StepUtils
 <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,23 +13,9 @@
 
 Binds animations into step, where the animation only runs as needed
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/StepUtils">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/steputils --save
-```
-
-## Usage
-Usage is designed to be simple.
-
-### `StepUtils.bindToRenderStep(update)`
-
-### `StepUtils.bindToSignal(signal, update)`
-
-### `StepUtils.onceAtRenderPriority(priority, func)`
-
-### `StepUtils.onceAtStepped(func)`
-
-### `StepUtils.onceAtRenderStepped(func)`
-
-### `StepUtils.onceAtEvent(event, func)`
-
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/steputils",
-  "version": "3.0.1-canary.9c1fd3b.0",
+  "version": "3.0.1",
   "description": "Binds animations into step, where the animation only runs as needed",
   "keywords": [
     "Roblox",
@@ -27,5 +27,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9c1fd3b43a16f8bc00caafbbb3f7092b4e5cc9eb"
+  "gitHead": "d146c77d0a8e452824de0ab0b4b03ba0370bcc1b"
 }

package/src/Shared/StepUtils.lua

@@ -1,17 +1,53 @@
---- Binds animations into step, where the animation only runs as needed
--- @module StepUtils
--- @author Quenty
+--[=[
+	Utility functions primarily used to bind animations into update loops of the Roblox engine.
+	@class StepUtils
+]=]
 
 local HttpService = game:GetService("HttpService")
 local RunService = game:GetService("RunService")
 
 local StepUtils = {}
 
--- update should return true while it needs to update
+--[=[
+	Binds the given update function to render stepped.
+
+	```lua
+	local spring = Spring.new(0)
+	local maid = Maid.new()
+
+	local startAnimation, maid._stopAnimation = StepUtils.bindToRenderStep(function()
+		local animating, position = SpringUtils.animating(spring)
+
+		print(position)
+
+		return animating
+	end)
+
+	spring.t = 1
+	startAnimation()
+	```
+
+	:::tip
+	Be sure to call the disconnect function when cleaning up, otherwise you may memory leak.
+	:::
+
+	@param update () -> boolean -- should return true while it needs to update
+	@return (...) -> () -- Connect function
+	@return () -> () -- Disconnect function
+]=]
 function StepUtils.bindToRenderStep(update)
 	return StepUtils.bindToSignal(RunService.RenderStepped, update)
 end
 
+--[=[
+	Binds an update event to a signal until the update function stops returning a truthy
+	value.
+
+	@param signal Signal | RBXScriptSignal
+	@param update () -> boolean -- should return true while it needs to update
+	@return (...) -> () -- Connect function
+	@return () -> () -- Disconnect function
+]=]
 function StepUtils.bindToSignal(signal, update)
 	if typeof(signal) ~= "RBXScriptSignal" then
 		error("signal must be of type RBXScriptSignal")
@@ -58,6 +94,14 @@ function StepUtils.bindToSignal(signal, update)
 	return connect, disconnect
 end
 
+--[=[
+	Calls the function once at the given priority level, unless the cancel callback is
+	invoked.
+
+	@param priority number
+	@param func function -- Function to call
+	@return function -- Call this function to cancel call
+]=]
 function StepUtils.onceAtRenderPriority(priority, func)
 	assert(type(priority) == "number", "Bad priority")
 	assert(type(func) == "function", "Bad func")
@@ -76,14 +120,39 @@ function StepUtils.onceAtRenderPriority(priority, func)
 	return cleanup
 end
 
+--[=[
+	Invokes the function once at stepped, unless the cancel callback is called.
+
+	```lua
+	-- Sometimes you need to defer the execution of code to make physics happy
+	maid:GiveTask(StepUtils.onceAtStepped(function()
+		part.CFrame = CFrame.new(0, 0, )
+	end))
+	```
+	@param func function -- Function to call
+	@return function -- Call this function to cancel call
+]=]
 function StepUtils.onceAtStepped(func)
 	return StepUtils.onceAtEvent(RunService.Stepped, func)
 end
 
+--[=[
+	Invokes the function once at renderstepped, unless the cancel callback is called.
+
+	@param func function -- Function to call
+	@return function -- Call this function to cancel call
+]=]
 function StepUtils.onceAtRenderStepped(func)
 	return StepUtils.onceAtEvent(RunService.RenderStepped, func)
 end
 
+--[=[
+	Invokes the function once at the given event, unless the cancel callback is called.
+
+	@param event Signal | RBXScriptSignal
+	@param func function -- Function to call
+	@return function -- Call this function to cancel call
+]=]
 function StepUtils.onceAtEvent(event, func)
 	assert(type(func) == "function", "Bad func")
 
@@ -103,5 +172,4 @@ function StepUtils.onceAtEvent(event, func)
 	return cleanup
 end
 
-
 return StepUtils

package/src/Shared/onRenderStepFrame.lua

@@ -1,9 +1,19 @@
---- Executes code at a specific point in render step priority queue
--- @module onRenderStepFrame
+--[=[
+	Executes code at a specific point in render step priority queue
+	@class onRenderStepFrame
+]=]
 
 local RunService = game:GetService("RunService")
 local HttpService = game:GetService("HttpService")
 
+--[=[
+	Executes code at a specific point in render step priority queue.
+	@function onRenderStepFrame
+	@param priority number
+	@return MaidTask
+	@within onRenderStepFrame
+]=]
+
 return function(priority, callback)
 	assert(type(priority) == "number", "Bad priority")
 	assert(type(callback) == "function", "Bad callback")

package/src/Shared/onSteppedFrame.lua

@@ -1,15 +1,24 @@
---- Executes code at a specific point in Roblox's engine
--- @module onSteppedFrame
+--[=[
+	Executes code at a specific point in Roblox's engine
+	@class onSteppedFrame
+]=]
 
 local RunService = game:GetService("RunService")
 
-return function(_function)
-	assert(type(_function) == "function", "Bad _function")
+--[=[
+	Executes code at a specific point in Roblox's engine.
+	@function onSteppedFrame
+	@param func function
+	@return RBXScriptConnection
+	@within onSteppedFrame
+]=]
+return function(func)
+	assert(type(func) == "function", "Bad func")
 
 	local conn
 	conn = RunService.Stepped:Connect(function()
 		conn:Disconnect()
-		_function()
+		func()
 	end)
 
 	return conn