New website beta (evaera#313)

Co-authored-by: Eleanor <[email protected]>

.gitignore

@@ -44,3 +44,4 @@ docs/CHANGELOG.md
 .vscode
 roblox.toml
 sourcemap.json
+build

.moonwave/custom.css

@@ -4,14 +4,19 @@
   --ifm-font-family-base: Inter, -apple-system, "Helvetica Neue", Roboto,
     Helvetica, system-ui, "Nimbus Sans", "Arial Nova", Arial, Segoe UI;
 
-  --ifm-font-family-monospace: ui-monospace, "Cascadia Code", "Source Code Pro",
-    Menlo, Consolas, "DejaVu Sans Mono", monospace;
-
   --ifm-navbar-link-hover-color: #9b59b6;
   --ifm-link-color: #9b59b6;
   --ifm-color-primary: #9b59b6;
 }
 
+.footer__copyright a:hover,
+code > a:hover {
+  text-decoration-thickness: 2px !important;
+  text-decoration: underline;
+}
+
+/* Navbar */
+
 .navbar__logo img {
   transition: opacity var(--ifm-transition-fast)
     var(--ifm-transition-timing-default);
@@ -21,11 +26,20 @@
   opacity: 75%;
 }
 
-.footer__copyright a {
+/* Footer */
+
+.footer a {
   color: var(--ifm-footer-color) !important;
+}
+
+.footer a:hover {
+  text-decoration: underline;
+}
+
+.footer__copyright a {
   text-decoration: underline;
 }
 
-.footer__copyright a:hover {
-  text-decoration: none !important;
+.footer__links {
+  text-align: center;
 }

Cmdr/BuiltInCommands/help.lua

@@ -36,16 +36,20 @@ return {
 			if command.Aliases and #command.Aliases > 0 then
 				context:Reply(`Aliases: {table.concat(command.Aliases, ", ")}`, Color3.fromRGB(230, 230, 230))
 			end
-			context:Reply(`Description: {command.Description}`, Color3.fromRGB(230, 230, 230))
+			if command.Description then
+				context:Reply(`Description: {command.Description}`, Color3.fromRGB(230, 230, 230))
+			end
 			if command.Group then
 				context:Reply(`Group: {command.Group}`, Color3.fromRGB(230, 230, 230))
 			end
-			for i, arg in ipairs(command.Args) do
-				context:Reply(
-					`#{i} {if type(arg) == "table"
-						then `{arg.Name}{if arg.Optional == true then "?" else ""}: {arg.Type} - {arg.Description}`
-						else "Unknown (inline argument)"}`
-				)
+			if command.Args then
+				for i, arg in ipairs(command.Args) do
+					context:Reply(
+						`#{i} {if type(arg) == "table"
+							then `{arg.Name}{if arg.Optional == true then "?" else ""}: {arg.Type} - {arg.Description}`
+							else "Unknown (inline argument)"}`
+					)
+				end
 			end
 		else
 			context:Reply(ARGUMENT_SHORTHANDS)
@@ -57,10 +61,10 @@ return {
 			end)
 			local lastGroup
 			for _, command in ipairs(commands) do
-				command.Group = command.Group or "No Group"
-				if lastGroup ~= command.Group then
-					context:Reply(`\n{command.Group}\n{string.rep("-", #command.Group)}`)
-					lastGroup = command.Group
+				local group = command.Group or "No Group"
+				if lastGroup ~= group then
+					context:Reply(`\n{group}\n{string.rep("-", #group)}`)
+					lastGroup = group
 				end
 				context:Reply(if command.Description then `{command.Name} - {command.Description}` else command.Name)
 			end

Cmdr/CmdrClient/init.lua

@@ -14,8 +14,7 @@ end
 --[=[
 	@class CmdrClient
 	@client
-
-	The Cmdr client singleton.
+	The Cmdr client singleton and entry point.
 ]=]
 
 --[=[
@@ -43,21 +42,21 @@ end
 	@within CmdrClient
 	@prop Enabled boolean
 	@readonly
-	TODO: Add description
+	Whether or not Cmdr is enabled (will show via the defined activation keys). Use [`CmdrClient:SetEnabled`](#SetEnabled) to change.
 ]=]
 
 --[=[
 	@within CmdrClient
 	@prop PlaceName string
 	@readonly
-	TODO: Add description
+	The current place name, displayed on the interface. Use [`CmdrClient:SetPlaceName`](#SetPlaceName) to change.
 ]=]
 
 --[=[
 	@within CmdrClient
 	@prop ActivationKeys { [Enum.KeyCode] = true }
 	@readonly
-	The list of key codes that will show or hide Cmdr. Use CmdrClient:SetActivationKeys to change.
+	The list of key codes that will show or hide Cmdr. Use [`CmdrClient:SetActivationKeys`](#SetActivationKeys) to change.
 ]=]
 
 local Cmdr
@@ -172,7 +171,8 @@ end
 
 --[=[
 	Enables the "Mash to open" feature.
-	TODO: Better description
+	This feature, when enabled, requires the activation key to be pressed 5 times within a second to [enable](#SetEnabled) Cmdr.
+	This may be helpful to guard against mispresses from opening the window, for example.
 
 	@within CmdrClient
 ]=]
@@ -186,7 +186,7 @@ end
 
 --[=[
 	Sets the hide on 'lost focus' feature.
-	TODO: Better description
+	This feature, which is enabled by default, will cause Cmdr to [hide](#Hide) when the user clicks off the window.
 
 	@within CmdrClient
 ]=]
@@ -195,16 +195,16 @@ function Cmdr:SetHideOnLostFocus(enabled: boolean)
 end
 
 --[=[
-	Sets the handler for a certain event type
-	TODO: Better description
+	Sets the [network event handler](/docs/networkeventhandlers) for a certain event type.
 
 	@within CmdrClient
 ]=]
 function Cmdr:HandleEvent(name: string, callback: (...any) -> ())
 	self.Events[name] = callback
 end
 
--- Only register when we aren't in studio because don't want to overwrite what the server portion did
+-- "Only register when we aren't in studio because don't want to overwrite what the server portion did"
+-- This is legacy code which predates Accurate Play Solo (which is now the only way to test in studio), this code will never run.
 if RunService:IsServer() == false then
 	Cmdr.Registry:RegisterTypesIn(script:WaitForChild("Types"))
 	Cmdr.Registry:RegisterCommandsIn(script:WaitForChild("Commands"))

Cmdr/Shared/Argument.lua

@@ -10,15 +10,7 @@ end
 
 --[=[
 	@class ArgumentContext
-	TODO: Description
-]=]
-
---[=[
-	@interface ArgumentDefinition
-	@within ArgumentContext
-	.Placeholder string
-
-	TODO:
+	Represents an individual argument within an individual command execution.
 ]=]
 
 local Argument = {}
@@ -40,7 +32,7 @@ Argument.__index = Argument
 
 --[=[
 	@prop Name string
-	The name of this argument.
+	The name of this argument, shown on the autocomplete interface.
 	@readonly
 	@within ArgumentContext
 ]=]
@@ -82,7 +74,7 @@ Argument.__index = Argument
 
 --[=[
 	@prop Prefix string
-	The prefix used in this argument (like `%` in `%Team`). Empty string if no prefix was used. See Prefixed Union Types for more details.
+	The prefix used in this argument (like `%` in `%Team`). Empty string if no prefix was used. See [Prefixed Union Types](/docs/commands#prefixed-union-types) for more details.
 	@readonly
 	@within ArgumentContext
 ]=]

Cmdr/Shared/Command.lua

@@ -6,17 +6,14 @@ local IsServer = RunService:IsServer()
 
 --[=[
 	@class CommandContext
-	TODO: Description
-]=]
-
---[=[
-	@interface CommandArgument
-	@within CommandContext
-	.Placeholder string
+	Represents an individual command execution.
 
-	TODO:
+	:::info Beta
+	This page is incomplete. You might want to refer to the [current documentation](https://eryn.io/Cmdr/api/CommandContext.html).
+	:::
 ]=]
 
+-- TODO: Add moonwave annotations
 local Command = {}
 Command.__index = Command
 

Cmdr/Shared/Registry.lua

@@ -14,19 +14,44 @@ local Util = require(script.Parent.Util)
 ]=]
 
 --[=[
-	@interface CommandDefinition
+	@interface ArgumentDefinition
 	@within Registry
-	.Placeholder string
+	.Type string | TypeDefinition -- The argument type (case sensitive), or an [inline TypeDefinition object](/docs/commands#dynamic-arguments-and-inline-types).
+	.Name string -- The argument name, this is displayed to the user as they type.
+	.Description string? -- A description of what the argument is, this is also displayed to the user.
+	.Optional boolean? -- If this is set to `true`, then the user can run the command without filling out the value. In which case, the argument will be sent to implementations as `nil`.
+	.Default any? -- If present, the argument will be automatically made optional, so if the user doesn't supply a value, implementations will receive whatever the value of `Default` is.
+
+	The `table` definition, usually contained in a [CommandDefinition](#CommandDefinition), which 'defines' the argument.
+]=]
 
-	TODO:
+--[=[
+	@interface CommandDefinition
+	@within Registry
+	.Name string -- The name of the command
+	.Aliases {string}? -- Aliases which aren't part of auto-complete, but if matched will run this command just the same. For example, `m` might be an alias of `announce`.
+	.Description string? -- A description of the command, displayed to the user in the `help` command and auto-complete menu.
+	.Group string? -- This property is intended to be used in hooks, so that you can categorise commands and decide if you want a specific user to be able to run them or not. But the `help` command will use them as headings.
+	.Args {ArgumentDefinition | (CommandContext) -> (ArgumentDefinition)} -- Arguments for the command; this is technically optional but if you have no args, set it to `{}` or you may experience some interface weirdness.
+	.Data (CommandContext, ...) -> any -- If your command needs to gather some extra data from the client that's only available on the client, then you can define this function. It should accept the command context and tuple of transformed arguments, and return a single value which will be available in the command with [CommandContext:GetData](/api/CommandContext#GetData).
+	.ClientRun (CommandContext, ...) -> string? -- If you want your command to run on the client, you can add this function to the command definition itself. It works exactly like the function that you would return from the Server module. If this function returns a string, the command will run entirely on the client and won't touch the server (which means server-only hooks won't run). If this function doesn't return anything, it will fall back to executing the Server module on the server.
+	.Run (CommandContext, ...) -> string? -- An older version of ClientRun. There are very few scenarios where this is preferred to ClientRun (so, in other words, don't use it!). These days, `Run` is only used for some dark magic involving server-sided command objects.
 ]=]
 
 --[=[
 	@interface TypeDefinition
 	@within Registry
-	.Placeholder string
+	.Prefixes string? -- String containing [prefixed union types](/docs/commands#prefixed-union-types) for this type. This property should omit the inital type, so the string should begin with a prefix character, e.g. `Prefixes = "# integer ! boolean"`
+	.DisplayName string? -- Overrides the user-facing name of this type in the autocomplete menu. Otherwise, the registered name of the type will be used.
+	.Default ((Player) -> string)? -- Should return the "default" value for this type as a string. For example, the default value of the `player` type is the name of the player who ran the command.
+	.Listable boolean? -- If true, this will tell Cmdr that comma-separated lists are allowed for this type. Cmdr will automatically split the list and parse each segment through your `Transform`, `Validate`, `Autocomplete` and `Parse` functions individually, so you don't have to change the logic of your type at all. The only limitation is that your `Parse` function **must return a table**, the tables from each individual segment's `Parse` functions will be merged into one table at the end of the parsing step. The uniqueness of values is ensured upon merging, so even if the user lists the same value several times, it will only appear once in the final table.
+	.Transform (string, Player) -> T? -- Transform is an optional function that is passed two values: the raw text, and the player running the command. Then, whatever values this function returns will be passed to all other functions in the type (`Validate`, `Autocomplete` and `Parse`).
+	.Validate (T) -> (boolean, string?) -- The `Validate` function is passed whatever is returned from the `Transform` function (or the raw value if there is no `Transform` function). If the value is valid for the type, it should return `true`. If the value is invalid, it should return two values: `false` and a string containing an error message. If this function is omitted, anything will be considered valid.
+	.ValidateOnce (T) -> (boolean, string?) -- This function works exactly the same as the normal `Validate` function, except it only runs once (after the user presses Enter). This should only be used if the validation process is relatively expensive or needs to yield. For example, the `playerId` type uses this because it needs to call `GetUserIdFromNameAsync` in order to validate. For the vast majority of types, you should just use `Validate` instead.
+	.Autocomplete (T) -> ({string}, {IsPartial: boolean?}?)? -- Should only be present for types that are possible to be auto-completed. It should return an array of strings that will be displayed in the auto-complete menu. It can also return a second value, containing a dictionary of options (currently, `IsPartial`: if true then pressing Tab to auto-complete won't continue onwards to the next argument.)
+	.Parse (T) -> any -- Parse is the only required function in a type definition. It is the final step before the value is considered finalised. This function should return the actual parsed value that will be sent to implementations.
 
-	TODO:
+	The `table` definition, contained in an [ArgumentDefinition](#ArgumentDefinition) or [registered](#RegisterType), which 'defines' the argument.
 ]=]
 
 --[=[
@@ -249,8 +274,8 @@ Registry.RegisterHooksIn = Registry.RegisterTypesIn
 --[=[
 	Register a command purely based on its definition.
 	Prefer using Registry:RegisterCommand for proper handling of client/server model.
-	@param commandObject CommandDefinition
 
+	@param commandObject CommandDefinition
 	@private
 	@within Registry
 ]=]

Cmdr/Shared/Util.lua

@@ -4,6 +4,10 @@ local TextService = game:GetService("TextService")
 	@class Util
 
 	Cmdr utilities module.
+
+	:::info Beta
+	This page is incomplete and some functions are missing. You might want to refer to [the current documentation](https://eryn.io/Cmdr/api/Util.html).
+	:::
 ]=]
 local Util = {}
 

Cmdr/init.lua

@@ -11,7 +11,7 @@ end
 	@class Cmdr
 	@server
 
-	The Cmdr server singleton.
+	The Cmdr server singleton and entry point.
 ]=]
 
 --[=[

docs/01-installation.md

@@ -0,0 +1,72 @@
+# Installation
+
+Cmdr has no dependencies which makes it incredibly portable and easy to include in your game.
+
+We recommend installing Cmdr in a place only visible on the server (such as `ServerScriptService` or `ServerStorage`). By installing it in a shared place (like `ReplicatedStorage`), installing to the server realm helps guard against mistakes and provides for better optimisation. Plus, there have sometimes been reports of weird, random issues caused by installing Cmdr in a shared place.
+
+You can choose one of many installation methods. While there are other potential installation methods, we recommend sticking to one of the below, unless you're sure you know what you're doing.
+
+:::info Heads up
+
+There are plenty of resources available to help you with Cmdr, such as this website and our Discord server, but we've been made aware of a number of DevForum guides and YouTube videos which provide incorrect or outdated instructions.
+
+**We recommend you stick to our official resources, especially if you're new to Cmdr.** If you decide to use unofficial resources, then the level of support we can provide (for instance in our Discord server) is limited.
+
+:::
+
+:::warning Do not modify the source code
+
+Please **do not** modify the source code of Cmdr for your game. Instead, use its API to customise the behaviour you want. Modifying the source code makes it much harder for you to receive future updates.
+
+There shouldn't be any reason why you need to modify the source code of Cmdr (unless you're [adding a new feature or fixing a bug](/docs/contribute)). If there's something you think we're missing, please [open an issue](https://github.com/evaera/cmdr/issues).
+
+:::
+
+## Model file (recommended)
+
+1. You can visit the [latest release](https://github.com/evaera/Cmdr/releases/latest) page. At the bottom of the page, you'll find an "Assets" section, then download `Cmdr.rbxm`
+
+If you're using Roblox Studio:
+
+1. You can either:
+   - drag or drop the `Cmdr.rbxm` file into the viewport (central window)
+   - select the `Model` tab, then under the `Advanced` section click `Model`. Then, navigate to the `Cmdr.rbxm` file and click `Open`
+2. Make sure you move the `Cmdr` ModuleScript to wherever you want it (as above, we recommend you keep it on the server)
+3. Proceed to [Setup](/docs/setup)
+
+If you're using Rojo, you can either add the `Cmdr.rbxm` file to your project file (usually called `default.project.json`), or put the `Cmdr.rbxm` file into a directory that you've got set up to sync already. [Rojo's documentation](https://rojo.space) can help you with this.
+
+## Wally (recommended) (requires Rojo)
+
+Cmdr is published on the wally registry as [`evaera/cmdr`](https://wally.run/package/evaera/cmdr); you should be cautious about the potential for malware and **only use the official package**.
+
+You can easily add Cmdr to your project's `wally.toml` file. If you're experiencing difficulties, [Wally's documentation](https://github.com/UpliftGames/wally#manifest-format) can help.
+
+We recommend adding Cmdr to the 'server realm', you can do this by putting it under the `server-dependencies` section. This'll put it in a `ServerPackages` folder (which you'll then need to sync into your game using Rojo).
+
+```toml
+[server-dependencies]
+Cmdr = "evaera/cmdr@^1.9.0"
+```
+
+Make sure you check what the [latest version](https://github.com/evaera/Cmdr/releases/latest) is. The caret (^) will tell Wally to automatically upgrade to the newest compatible version if available, which we recommend doing.
+
+## Submodule (advanced) (requires Rojo)
+
+If your project is using Rojo and Git, then you can use Git Submodules to include Cmdr into your project, and then sync it into your game using Rojo.
+
+This will include a lot of unnecessary files into your project though, like the website and documentation, so you should make sure you only pull or sync the `Cmdr` directory (which is the library source code).
+
+We recommend 'pinning' to the [latest version](https://github.com/evaera/Cmdr/releases/latest)'s tag, rather than using the `master` branch. This is because pre-release versions may have unexpected bugs, glitches or changes, and we may not be able to offer you support unless you're using the latest released version.
+
+## Manual (not recommended) (requires Rojo)
+
+Using `git clone` or GitHub's Download button, you can download a copy of the source code and then take the `Cmdr` directory and sync this into your place.
+
+We recommend downloading the [latest version](https://github.com/evaera/Cmdr/releases/latest) rather than using the `master` branch. This is because pre-release versions may have unexpected bugs, glitches or changes, and we may not be able to offer you support unless you're using the latest released version.
+
+## Roblox models (not supported)
+
+Cmdr is not published to the Roblox creator marketplace. Owing to the prevalence of malware, you **should not use any publish of Cmdr on the Roblox library**, and instead use one of the above installation methods.
+
+If you're experiencing difficulties and need help, then you can find advice on getting help [in the Introduction page](/docs/intro).