From 04577a0a465a26c542e4d509ed484aba0bf7cd7a Mon Sep 17 00:00:00 2001
From: Kenny <70860732+KennyOliver@users.noreply.github.com>
Date: Mon, 20 Jan 2025 01:58:41 +0000
Subject: [PATCH] Update: Documentation for new `sample()` prompt syntax

#245
---
 docs/brainf_interpreter.md |  3 +--
 docs/language_design.md    | 46 +++++++++++++++++++-------------------
 docs/standard_library.md   | 10 ++++++---
 docs/tutorial.md           |  3 +--
 4 files changed, 32 insertions(+), 30 deletions(-)

diff --git a/docs/brainf_interpreter.md b/docs/brainf_interpreter.md
index 3284384..2955040 100644
--- a/docs/brainf_interpreter.md
+++ b/docs/brainf_interpreter.md
@@ -87,8 +87,7 @@ create brainf_interpreter(code) {
             let character = chr(ascii_val);
             serve(character, False);
         } elif command == "," {
-            serve("Input a character:");
-            let input_char = sample();
+            let input_char = sample("Input a character:");
             let ascii_val = ord(input_char);
             data_tape[data_ptr] = ascii_val;
         } elif command == "[" {
diff --git a/docs/language_design.md b/docs/language_design.md
index d782fa5..8aabca7 100644
--- a/docs/language_design.md
+++ b/docs/language_design.md
@@ -33,29 +33,29 @@ FlavorLang is a programming language designed with a cooking-inspired syntax, co
 
 ### 1. Keywords
 
-| Category                 | Keyword   | Description                    | Example                     |
-| ------------------------ | --------- | ------------------------------ | --------------------------- |
-| **Variable Declaration** | `let`     | Mutable variable declaration   | `let x = 5;`                |
-|                          | `const`   | Immutable constant declaration | `const PI = 3.14;`          |
-| **Control Flow**         | `if`      | Conditional execution          | `if condition { ... }`      |
-|                          | `elif`    | Alternative condition          | `elif condition { ... }`    |
-|                          | `else`    | Default condition              | `else { ... }`              |
-|                          | `for`     | Loop iteration                 | `for i in range { ... }`    |
-|                          | `while`   | Conditional loop               | `while condition { ... }`   |
-|                          | `break`   | Exit loop or switch            | `break;`                    |
-| **Pattern Matching**     | `check`   | Pattern matching construct     | `check value { ... }`       |
-|                          | `is`      | Pattern case                   | `is pattern:`               |
-| **Functions**            | `create`  | Function declaration           | `create func() { ... }`     |
-|                          | `deliver` | Return value                   | `deliver result;`           |
-| **Error Handling**       | `try`     | Exception handling             | `try { ... }`               |
-|                          | `rescue`  | Error catching                 | `rescue { ... }`            |
-|                          | `finish`  | Cleanup block                  | `finish { ... }`            |
-|                          | `burn`    | Raise error                    | `burn "Error message";`     |
-| **I/O Operations**       | `serve`   | Output                         | `serve("message");`         |
-|                          | `sample`  | Input                          | `let input = sample();`     |
-|                          | `plate`   | File write                     | `plate_file(path, data);`   |
-|                          | `garnish` | File append                    | `garnish_file(path, data);` |
-|                          | `taste`   | File read                      | `taste_file(path);`         |
+| Category                 | Keyword   | Description                    | Example                                  |
+| ------------------------ | --------- | ------------------------------ | ---------------------------------------- |
+| **Variable Declaration** | `let`     | Mutable variable declaration   | `let x = 5;`                             |
+|                          | `const`   | Immutable constant declaration | `const PI = 3.14;`                       |
+| **Control Flow**         | `if`      | Conditional execution          | `if condition { ... }`                   |
+|                          | `elif`    | Alternative condition          | `elif condition { ... }`                 |
+|                          | `else`    | Default condition              | `else { ... }`                           |
+|                          | `for`     | Loop iteration                 | `for i in range { ... }`                 |
+|                          | `while`   | Conditional loop               | `while condition { ... }`                |
+|                          | `break`   | Exit loop or switch            | `break;`                                 |
+| **Pattern Matching**     | `check`   | Pattern matching construct     | `check value { ... }`                    |
+|                          | `is`      | Pattern case                   | `is pattern:`                            |
+| **Functions**            | `create`  | Function declaration           | `create func() { ... }`                  |
+|                          | `deliver` | Return value                   | `deliver result;`                        |
+| **Error Handling**       | `try`     | Exception handling             | `try { ... }`                            |
+|                          | `rescue`  | Error catching                 | `rescue { ... }`                         |
+|                          | `finish`  | Cleanup block                  | `finish { ... }`                         |
+|                          | `burn`    | Raise error                    | `burn "Error message";`                  |
+| **I/O Operations**       | `serve`   | Output                         | `serve("message");`                      |
+|                          | `sample`  | Input                          | `let input = sample("Enter a number:");` |
+|                          | `plate`   | File write                     | `plate_file(path, data);`                |
+|                          | `garnish` | File append                    | `garnish_file(path, data);`              |
+|                          | `taste`   | File read                      | `taste_file(path);`                      |
 
 ### 2. Data Types
 
diff --git a/docs/standard_library.md b/docs/standard_library.md
index a010cda..9946136 100644
--- a/docs/standard_library.md
+++ b/docs/standard_library.md
@@ -14,7 +14,7 @@ The FlavorLang Standard Library provides a comprehensive set of built-in functio
      - [`float(value) → float`](#floatvalue--float)
      - [`int(value) → int`](#intvalue--int)
    - [Input/Output](#inputoutput)
-     - [`sample() → string`](#sample--string)
+     - [`sample(prompt) → string`](#sampleprompt--string)
      - [`serve(*args, newline=True)`](#serveargs-newlinetrue)
    - [Error Handling](#error-handling)
      - [`burn(*messages)`](#burnmessages)
@@ -110,9 +110,13 @@ int("-17");  # -17
 
 ### Input/Output
 
-#### `sample() → string`
+#### `sample(prompt) → string`
 
-Reads a line of input from the terminal.
+Reads a line of input from the terminal with an optional prompt.
+
+**Parameters:**
+
+- `prompt`: any value
 
 **Returns:**
 
diff --git a/docs/tutorial.md b/docs/tutorial.md
index ce6709d..3635087 100644
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@@ -66,8 +66,7 @@ serve("Multiple", "values", "work"); # Spaces between values
 Use `sample()` to get user input:
 
 ```js
-serve("What's your favorite dish?");
-let favorite = sample();
+let favorite = sample("What's your favorite dish?");
 serve("Ah,", favorite, "is delicious!");
 ```