From fe5836911ca05d7f984e7dd97ea4c472efa947d4 Mon Sep 17 00:00:00 2001
From: Gabriele Invernizzi <gabrieleinvernizzi4@gmail.com>
Date: Thu, 2 Jan 2025 15:48:23 +0100
Subject: [PATCH] Updated documentation

---
 src/Themes/Theme.zig | 4 ++++
 src/prompt.zig       | 7 +++++++
 2 files changed, 11 insertions(+)

diff --git a/src/Themes/Theme.zig b/src/Themes/Theme.zig
index f7f4b28..6a295da 100644
--- a/src/Themes/Theme.zig
+++ b/src/Themes/Theme.zig
@@ -27,9 +27,13 @@ pub const Options = struct {
 
 /// Stores all the format functions used in the `Theme` struct.
 pub const VTable = struct {
+    /// Used to format `Prompt.string(...)` prompt.
     format_string_prompt_fn: *const fn (ptr: *const anyopaque, wrt: Writer, prompt: []const u8, default: ?[]const u8, max_len: ?usize) anyerror!void,
+    /// Used to format `Prompt.option(...)` prompt.
     format_option_prompt_fn: *const fn (ptr: *const anyopaque, wrt: Writer, prompt: []const u8) anyerror!void,
+    /// Used to format `Prompt.option(...)` option line.
     format_option_opt_fn: *const fn (_: *const anyopaque, wrt: Writer, opt: []const u8, is_selected: bool) anyerror!void,
+    /// Used to format `Prompt.option(...)` password.
     format_passwd_prompt_fn: *const fn (ptr: *const anyopaque, wrt: Writer, prompt: []const u8, max_len: ?usize) anyerror!void,
 };
 
diff --git a/src/prompt.zig b/src/prompt.zig
index 73b0c25..cf8b52f 100644
--- a/src/prompt.zig
+++ b/src/prompt.zig
@@ -24,6 +24,8 @@ pub fn init(allocator: Allocator, theme: Theme) Self {
 
 /// Asks the user for a string with the provided `prompt`.
 /// If the user does not enter any non whitespace chars the function returns the `default`.
+/// In case of success the function will return an owned slice.
+/// Free the return value using the allocator provided in `init`.
 pub fn string(self: *Self, prompt: []const u8, default: ?[]const u8) ![]const u8 {
     const out = std.io.getStdOut().writer();
     const in = std.io.getStdIn().reader();
@@ -53,6 +55,8 @@ pub fn string(self: *Self, prompt: []const u8, default: ?[]const u8) ![]const u8
 }
 
 /// Similar to `Prompt.string(...)` but it also validate the input with `validator`.
+/// In case of success the function will return an owned slice.
+/// Free the return value using the allocator provided in `init`.
 pub fn stringValidated(self: *Self, prompt: []const u8, default: ?[]const u8, validator: ValidatorFn) ![]const u8 {
     const out = std.io.getStdOut().writer();
 
@@ -68,6 +72,8 @@ pub fn stringValidated(self: *Self, prompt: []const u8, default: ?[]const u8, va
 }
 
 /// Asks the user a confirmation with the `prompt` provided.
+/// In case of success the function will return `true` if the value inserted by the user
+/// was affermative and `false` otherwise.
 pub fn confirm(self: *Self, prompt: []const u8) !bool {
     const out = std.io.getStdOut().writer();
 
@@ -153,6 +159,7 @@ pub fn option(self: *Self, prompt: []const u8, opts: []const []const u8, default
 /// Asks the user for a password with the provieded `prompt`.
 /// The echoing of an indicator character as the user types can be set via the `Theme`.
 /// The operation can be aborted using ctrl-c, then the function returns `null`.
+/// In case of success the function will return a slice over `buf`.
 pub fn password(self: *Self, prompt: []const u8, buf: []u8) !?[]const u8 {
     const stdin = std.io.getStdIn();
     const out = std.io.getStdOut().writer();