From eb77336fd42a749411d7d24b50099df24497be07 Mon Sep 17 00:00:00 2001
From: Miguel Young de la Sota <mcyoung@mit.edu>
Date: Thu, 11 Jul 2024 19:34:01 -0400
Subject: [PATCH] docs

---
 best/cli/app.h    |  9 +++++++--
 best/cli/cli.h    | 17 +++++++++++++----
 best/cli/parser.h |  3 +--
 3 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/best/cli/app.h b/best/cli/app.h
index ee3e0a3..f3cd8fb 100644
--- a/best/cli/app.h
+++ b/best/cli/app.h
@@ -45,12 +45,17 @@ namespace best {
 /// namespace scope in your main file.
 ///
 /// ```
-/// best::app MyApp = +[](best::vec<best::strbuf> args) {
+/// best::app MyApp = [](MyFlags& args) {
 ///   // Your code here!
 /// };
 /// ```
 ///
-/// So, what can go in `args`?
+/// So, what can go in `args`? It's a flags struct! See `cli.h` for more
+/// information on how to define one. Alternatively, you can simply take zero
+/// arguments, and interpret `best::app::argv()` yourself.
+///
+/// The function must return either `void`, `int`, or a result whose error type
+/// is printable.
 class app final {
  public:
   /// # `app::app()`
diff --git a/best/cli/cli.h b/best/cli/cli.h
index d6f73ab..278a3e8 100644
--- a/best/cli/cli.h
+++ b/best/cli/cli.h
@@ -31,14 +31,23 @@
 //!
 //! This header provides functionality for parsing CLI flags from program
 //! inputs. In `best`, CLI flags are defined as a reflectable struct with
-//! usage, flag, parse, and validation information attached to them. This means
-//! that it's easy to construct flag structs independently of the actual argv
-//! of the program, promoting decoupling.
+//! usage, flag, parse, and validation information attached to its fields as
+//! tags.
+//!
+//! This means that it's easy to construct flag structs independently of
+//! actual flag parsing: they're "just" structs! This design pattern is heavily
+//! inspired by some Rust CLI crates, such as clap, structopt, and argh.
+//!
+//! For an example flags struct, see `toy_flags.h` and `toy.cc`. Note that
+//! the actual parsing functions live in `cli/parser.h`. This is so that this
+//! header is comparatively light-weight to the parser header; this header
+//! does not pull in reflection.
 
 namespace best {
 /// # `best::cli`
 ///
-/// A flags struct parser.
+/// A flags struct parser. Currently this has no user-accessible functions, but
+/// it does contain all of the types necessary for defining a flags struct.
 class cli final {
  public:
   /// # `cli::visibility`
diff --git a/best/cli/parser.h b/best/cli/parser.h
index 35561d0..6196c23 100644
--- a/best/cli/parser.h
+++ b/best/cli/parser.h
@@ -31,8 +31,7 @@
 #include "best/text/strbuf.h"
 #include "best/text/utf8.h"
 
-//! Command-line flags.
-//!
+//! Command-line flag parsing. See `cli.h` for more information.
 
 namespace best {
 /// # `best::cli_flags()`