docs: add jsdoc for text, password, and multiline prompts (#523)

Co-authored-by: paul valladares <85648028+dreyfus92@users.noreply.github.com>

Author: ghostdevv

.changeset/five-chicken-hide.md

@@ -0,0 +1,5 @@
+---
+"@clack/prompts": patch
+---
+
+docs: add jsdoc for `text`, `password`, and `multiline` prompts

packages/prompts/README.md

@@ -65,7 +65,7 @@ const meaning = await text({
 
 ### Password
 
-The password component behaves like `text`, but masks the input as the user types.
+The password prompt behaves like the [`text`](#text) prompt, but masks the input as the user types.
 
 ```js
 import { password } from '@clack/prompts';
@@ -201,7 +201,7 @@ const basket = await groupMultiselect({
 
 ### Multi-Line Text
 
-The multi-line text component accepts multiple lines of text input. By default, pressing `Enter` twice submits the input.
+The multi-line prompt accepts multiple lines of text input. By default, pressing `Enter` twice submits the input.
 
 ```js
 import { multiline } from '@clack/prompts';

packages/prompts/src/multi-line.ts

@@ -3,10 +3,36 @@ import { MultiLinePrompt, settings, wrapTextWithPrefix } from '@clack/core';
 import { S_BAR, S_BAR_END, symbol } from './common.js';
 import type { TextOptions } from './text.js';
 
+/**
+ * Options for the {@link multiline} prompt
+ */
 export interface MultiLineOptions extends TextOptions {
+	/**
+	 * When enabled it shows a `[ submit ]` button that can be focused with tab.
+	 * By default, pressing `Enter` twice submits the input
+	 *
+	 * @default false
+	 */
 	showSubmit?: boolean;
 }
 
+/**
+ * The multi-line prompt accepts multiple lines of text input.
+ * By default, pressing `Enter` twice submits the input.
+ *
+ * @see https://bomb.sh/docs/clack/packages/prompts/#multi-line-text
+ *
+ * @example
+ * ```ts
+ * import { multiline } from '@clack/prompts';
+ *
+ * const bio = await multiline({
+ *   message: 'Enter your bio',
+ *   placeholder: 'Tell us about yourself...',
+ *   showSubmit: true,
+ * });
+ * ```
+ */
 export const multiline = (opts: MultiLineOptions) => {
 	return new MultiLinePrompt({
 		validate: opts.validate,

packages/prompts/src/password.ts

@@ -2,12 +2,48 @@ import { styleText } from 'node:util';
 import { PasswordPrompt, settings } from '@clack/core';
 import { type CommonOptions, S_BAR, S_BAR_END, S_PASSWORD_MASK, symbol } from './common.js';
 
+/**
+ * Options for the {@link password} prompt
+ */
 export interface PasswordOptions extends CommonOptions {
+	/**
+	 * The prompt message or question shown to the user above the input.
+	 */
 	message: string;
+
+	/**
+	 * Character to use for masking input.
+	 * @default ▪/•
+	 */
 	mask?: string;
+
+	/**
+	 * A function that validates user input. Return a `string` or `Error` to show as a
+	 * validation error, or `undefined` to accept the result.
+	 */
 	validate?: (value: string | undefined) => string | Error | undefined;
+
+	/**
+	 * When enabled it causes the input to be cleared if/when validation fails.
+	 * @default false
+	 */
 	clearOnError?: boolean;
 }
+
+/**
+ * The password prompt behaves like the {@link text} prompt, but the input is masked.
+ *
+ * @see https://bomb.sh/docs/clack/packages/prompts/#password-input
+ *
+ * @example
+ * ```ts
+ * import { password } from '@clack/prompts';
+ *
+ * const result = await password({
+ *   message: 'Enter your password',
+ * });
+ * ```
+ */
 export const password = (opts: PasswordOptions) => {
 	return new PasswordPrompt({
 		validate: opts.validate,

packages/prompts/src/text.ts

@@ -2,14 +2,57 @@ import { styleText } from 'node:util';
 import { settings, TextPrompt } from '@clack/core';
 import { type CommonOptions, S_BAR, S_BAR_END, symbol } from './common.js';
 
+/**
+ * Options for the {@link text} prompt
+ */
 export interface TextOptions extends CommonOptions {
+	/**
+	 * The prompt message or question shown to the user above the input.
+	 */
 	message: string;
+
+	/**
+	 * A visual hint shown when the field has no content.
+	 */
 	placeholder?: string;
+
+	/**
+	 * A fallback value returned when the user provides nothing (empty input).
+	 */
 	defaultValue?: string;
+
+	/**
+	 * The starting value shown when the prompt first renders.
+	 * Users can edit this value before submitting.
+	 */
 	initialValue?: string;
+
+	/**
+	 * A function that validates user input. Return a `string` or `Error` to show as a
+	 * validation error, or `undefined` to accept the result.
+	 */
 	validate?: (value: string | undefined) => string | Error | undefined;
 }
 
+/**
+ * The text prompt accepts a single line of text.
+ *
+ * @see https://bomb.sh/docs/clack/packages/prompts/#text-input
+ *
+ * @example
+ * ```ts
+ * import { text } from '@clack/prompts';
+ *
+ * const name = await text({
+ *   message: 'What is your name?',
+ *   placeholder: 'John Doe',
+ *   validate: (value) => {
+ *     if (!value || value.length < 2) return 'Name must be at least 2 characters';
+ *     return undefined;
+ *   },
+ * });
+ * ```
+ */
 export const text = (opts: TextOptions) => {
 	return new TextPrompt({
 		validate: opts.validate,