docs: improve decorator and type docs

docs/src/content/docs/reference/decorators.mdx

@@ -21,6 +21,9 @@ export class MyCommand {
 
 Defines a command.
 
+**Parameters**:
+- **options**: `CommandOptions` The command's options.
+
 ### Usage
 
 <Code lang="ts" code={`
@@ -43,6 +46,9 @@ Assigns a command to one or more groups.
 When a class is decorated with this decorator, all commands within the
 class will be assigned to the group.
 
+**Parameters**:
+- **groups**: `...string[]` The groups to assign to the command.
+
 ### Usage
 
 <Code lang="ts" code={`
@@ -70,6 +76,9 @@ Assigns one or more guards to a command.
 When a class is decorated with this decorator, the provided guard(s) will
 be assigned to all commands within the class.
 
+**Parameters**:
+- **guards**: `...CommandGuard[]` The guards to assign to the command.
+
 ### Usage
 
 <Code lang="ts" code={`
@@ -83,26 +92,15 @@ ban() {}
 
 ## `CommandOptions`
 
-- name: string;
-
-The name of the command.
-
-- aliases?: string[];
-
-An array of aliases for the command.
-
-- description?: string;
-
-The command's description.
-
-- arguments?: ArgumentOptions[];
-
-The command's arguments.
+- **name**: `string` - The name of the command.
+- **aliases**: `string[]?` - An array of aliases for the command.
+- **description**: `string?` - The command's description.
+- **arguments**: `ArgumentOptions[]?` - The command's arguments.
 
 ## `ArgumentOptions`
 
-- name: `string` - The name of the argument.
-- type: `string` - The argument's type. Must be the name of a registered type.
-- (**optional**) optional: `boolean` - Whether the argument is optional.
-- (**optional**) suggestions: `string[]` - An array of suggestions for the argument.
+- **name**: `string` - The name of the argument.
+- **type**: `string` - The argument's type. Must be the name of a registered type.
+- **optional**: `boolean?` - Whether the argument is optional.
+- **suggestions**: `string[]?` - An array of suggestions for the argument.
 These will be added to the suggestions returned by the argument's type.

docs/src/content/docs/reference/types.mdx

@@ -15,7 +15,7 @@ for the type.
 
 ## `TypeBuilder`
 
-A helper class for creating argument types.
+A helper class for building argument types.
 
 ### `create(name)`
 
@@ -27,14 +27,14 @@ Instantiates a `TypeBuilder` with the given name.
 **Returns**:
 A `TypeBuilder` instance.
 
-### `extend(name, options)`
+### `extend(name, argumentType)`
 
 Creates a new `TypeBuilder` with the given name, extending
 from the provided type.
 
 **Parameters**:
 - `name` - The name of the type.
-- `options` - The type to extend from.
+- `argumentType` - The type to extend from.
 
 **Returns**:
 A `TypeBuilder` instance.
@@ -78,14 +78,16 @@ The `TypeBuilder` instance.
 
 ### `build()`
 
-Builds the type, returning an `ArgumentType` object.
+Builds the type, returning an [ArgumentType](#argumenttype) object.
 
-This function also marks the type for registration, so it will be registered
-when calling [BaseRegistry.register](../registry#register), as long as the module
-is loaded.
+This function marks the type for registration, meaning it will be registered
+when calling `register` if the module was loaded.
+
+**Throws**:
+Will throw an error if the required functions were not defined
 
 **Returns**:
-An `ArgumentType` object.
+An [ArgumentType](#argumenttype) object.
 
 ## `TransformResult`
 

packages/core/src/shared/util/type.ts

@@ -10,9 +10,10 @@ export namespace TransformResult {
 	export type Object<T> = { ok: true; value: T } | { ok: false; value: string };
 
 	/**
-	 * Produces a successful `Result`, indicating that a transformation was successful.
+	 * Creates a successful result object, indicating a transformation was successful.
 	 *
-	 * @param value - The resulting value of the transformation
+	 * @param value - The transformed value.
+	 * @returns A {@link TransformResult.Object} object.
 	 */
 	export function ok<T>(value: T): Object<T> {
 		return {
@@ -22,9 +23,10 @@ export namespace TransformResult {
 	}
 
 	/**
-	 * Produces a failed `Result`, indicating that a transformation was not successful.
+	 * Creates an error result object, indicating a transformation was not successful.
 	 *
 	 * @param text - The error message
+	 * @returns A {@link TransformResult.Object} object.
 	 */
 	export function err<T>(text: string): Object<T> {
 		return {
@@ -34,6 +36,9 @@ export namespace TransformResult {
 	}
 }
 
+/**
+ * A helper class for building argument types.
+ */
 export class TypeBuilder<T> {
 	protected expensive = false;
 	protected validationFn?: t.check<T>;
@@ -43,77 +48,81 @@ export class TypeBuilder<T> {
 	protected constructor(protected readonly name: string) {}
 
 	/**
-	 * Creates a {@link TypeBuilder}.
+	 * Instantiates a {@link TypeBuilder} with the given name.
 	 *
-	 * @param name - The name of the type
-	 * @returns A type builder
+	 * @param name - The name of the type.
+	 * @returns A {@link TypeBuilder} instance.
 	 */
 	static create<T>(name: string) {
 		return new TypeBuilder<T>(name);
 	}
 
 	/**
-	 * @param name - The name of the type
-	 * @param options - The type to extend from
-	 * @returns A builder extended from the given type
+	 * Creates a new `TypeBuilder` with the given name, extending
+	 * from the provided type.
+	 *
+	 * @param name - The name of the type.
+	 * @param argumentType - The type to extend from.
+	 * @returns A {@link TypeBuilder} instance.
 	 */
-	static extend<T>(name: string, options: ArgumentType<T>) {
+	static extend<T>(name: string, argumentType: ArgumentType<T>) {
 		const builder = new TypeBuilder<T>(name);
-		builder.expensive = options.expensive;
-		builder.validationFn = options.validate;
-		builder.transformFn = options.transform;
-		builder.suggestionFn = options.suggestions;
+		builder.expensive = argumentType.expensive;
+		builder.validationFn = argumentType.validate;
+		builder.transformFn = argumentType.transform;
+		builder.suggestionFn = argumentType.suggestions;
 		return builder;
 	}
 
 	/**
 	 * Sets the validation function for this type.
 	 *
-	 * @param validationFn - The type guard used to validate this type
-	 * @returns The type builder
+	 * @param fn - The validation function.
+	 * @returns The {@link TypeBuilder} instance.
 	 */
-	validate(validationFn: t.check<T>) {
-		this.validationFn = validationFn;
+	validate(fn: t.check<T>) {
+		this.validationFn = fn;
 		return this;
 	}
 
 	/**
 	 * Sets the transformation function for this type.
 	 *
-	 * If the `expensive` parameter is set to true, it indicates that
-	 * the transform function will be expensive to compute. If the default
-	 * interface is being used in this case, it will disable real-time
-	 * checking while the user is typing the command.
+	 * If the `expensive` parameter is `true`, it indicates the transformation
+	 * function is expensive to compute. If the default interface is used, type-checking
+	 * will be disabled while typing an argument.
 	 *
-	 * @param callback - The transformation function for this type
-	 * @param expensive - Whether the function is expensive to compute
-	 * @returns The type builder
+	 * @param fn - The transformation function.
+	 * @param expensive - Whether the function is expensive.
+	 * @returns The {@link TypeBuilder} instance.
 	 */
-	transform(callback: TransformFn<T>, expensive = false) {
-		this.transformFn = callback;
+	transform(fn: TransformFn<T>, expensive = false) {
+		this.transformFn = fn;
 		this.expensive = expensive;
 		return this;
 	}
 
 	/**
 	 * Sets the suggestion function for this type.
 	 *
-	 * This function should provide a list of suggestions for this type.
+	 * This function provides a list of suggestions for the type.
 	 *
-	 * @param callback - The suggestion function for this type
-	 * @returns The type builder
+	 * @param fn - The suggestions function.
+	 * @returns The {@link TypeBuilder} instance.
 	 */
-	suggestions(callback: SuggestionFn<T>) {
-		this.suggestionFn = callback;
+	suggestions(fn: SuggestionFn<T>) {
+		this.suggestionFn = fn;
 		return this;
 	}
 
 	/**
-	 * Creates a {@link ArgumentType} using the options that were provided to the builder.
+	 * Builds the type, returning an {@link ArgumentType} object.
 	 *
-	 * @throws Will throw an error if the required options were not provided
+	 * This function marks the type for registration, meaning it will be registered
+	 * when calling `register` if the module was loaded.
 	 *
-	 * @returns A {@link ArgumentType} created from the options provided to the builder
+	 * @throws Will throw an error if the required functions were not defined
+	 * @returns An {@link ArgumentType} object.
 	 */
 	build(): ArgumentType<T> {
 		assert(this.validationFn !== undefined, "Validation function is required");