From 1e3f3df9209b97c3d1b98204a888dfda95db0ade Mon Sep 17 00:00:00 2001
From: Tony Gorez <tonygo@tonys-macbook-pro.home>
Date: Tue, 27 Feb 2024 12:24:00 +0100
Subject: [PATCH] refactor/doc: tweak api

Signed-off-by: Tony Gorez <tonygo@tonys-macbook-pro.home>
---
 README.md                               | 27 ++++++++++++++++++++++++-
 examples/simple_prompt.cc               | 15 +++++++-------
 src/prompt/include/qupp/prompt/prompt.h |  9 ++++-----
 src/prompt/unix/prompt.cc               |  7 ++++---
 4 files changed, 42 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 068be5c..db85043 100644
--- a/README.md
+++ b/README.md
@@ -10,15 +10,40 @@
 - 🌍 Cross-platform (work in progress).
 - 🛠️ CMake-friendly integration (work in progress)
 
-## 📖 Usage
+## 📖 Usage (API)
+
+### `std::optional<std::string> Prompt::ask_for_input(std::string question)`
 
 ```cpp
 #include <qupp/prompt/prompt.h>
 
 int main() {
     qupp::prompt::Prompt prompt;
+
     auto result = prompt.ask_for_input("What's your name? ");
     std::cout << "Hello, " << result.value() << "!" << std::endl;
+
+    return 0;
+}
+```
+
+### `std::optional<std::string> Prompt::ask_from_list(std::string question, std::vector<std::string> options)`
+
+```cpp
+#include <qupp/prompt/prompt.h>
+
+int main() {
+    qupp::prompt::Prompt prompt;
+
+   auto selected = prompt.select_from_list(
+       "Select an option:", {"Option 1", "Option 2", "Option 3 "});
+   if (selected.has_value()) {
+     std::cout << "You selected: " << selected.value() << "\n";
+   } else {
+     std::cout << "You did not select anything."
+               << "\n";
+   }
+
     return 0;
 }
 ```
diff --git a/examples/simple_prompt.cc b/examples/simple_prompt.cc
index 0f8393b..ad31860 100644
--- a/examples/simple_prompt.cc
+++ b/examples/simple_prompt.cc
@@ -5,6 +5,14 @@
 int main() {
   qupp::prompt::Prompt prompt;
 
+  auto result = prompt.ask_for_input("What is your name?");
+  if (result.has_value()) {
+    std::cout << "Hello " << result.value() << "\n";
+  } else {
+    std::cout << "Hello, I did not get your name."
+              << "\n";
+  }
+
   auto selected = prompt.select_from_list(
       "Select an option:", {"Option 1", "Option 2", "Option 3 "});
   if (selected.has_value()) {
@@ -13,11 +21,4 @@ int main() {
     std::cout << "You did not select anything."
               << "\n";
   }
-
-  auto result = prompt.ask_for_input("This is a question:");
-  if (result.has_value()) {
-    std::cout << "You answered: " << result.value() << std::endl;
-  } else {
-    std::cout << "You did not answer." << std::endl;
-  }
 }
diff --git a/src/prompt/include/qupp/prompt/prompt.h b/src/prompt/include/qupp/prompt/prompt.h
index 37a643c..7597f98 100644
--- a/src/prompt/include/qupp/prompt/prompt.h
+++ b/src/prompt/include/qupp/prompt/prompt.h
@@ -8,17 +8,16 @@
 
 namespace qupp::prompt {
 
-using StringResult = std::optional<std::string>;
-
 struct Prompt {
   // The explicit keyword is used to avoid implicit conversions.
   Prompt(qupp::io::TerminalInterface &terminal =
              qupp::io::Terminal::get_instance());
 
-  StringResult ask_for_input(const std::string &message);
+  std::optional<std::string> ask_for_input(const std::string &message);
 
-  StringResult select_from_list(const std::string &message,
-                                const std::vector<std::string> &options);
+  std::optional<std::string>
+  select_from_list(const std::string &message,
+                   const std::vector<std::string> &options);
 
 private:
   qupp::io::TerminalInterface &terminal_;
diff --git a/src/prompt/unix/prompt.cc b/src/prompt/unix/prompt.cc
index be009aa..93ff50c 100644
--- a/src/prompt/unix/prompt.cc
+++ b/src/prompt/unix/prompt.cc
@@ -5,7 +5,7 @@
 namespace qupp::prompt {
 Prompt::Prompt(qupp::io::TerminalInterface &terminal) : terminal_(terminal) {}
 
-StringResult Prompt::ask_for_input(const std::string &question) {
+std::optional<std::string> Prompt::ask_for_input(const std::string &question) {
   if (question.empty()) {
     return std::nullopt;
   }
@@ -14,8 +14,9 @@ StringResult Prompt::ask_for_input(const std::string &question) {
   return terminal_.read_from_console();
 }
 
-StringResult Prompt::select_from_list(const std::string &question,
-                                      const std::vector<std::string> &options) {
+std::optional<std::string>
+Prompt::select_from_list(const std::string &question,
+                         const std::vector<std::string> &options) {
   if (question.empty() || options.empty()) {
     return std::nullopt;
   }