Add documentations to every public functions.

src/ftxui/component/component_options.cpp

@@ -13,33 +13,55 @@
 
 namespace ftxui {
 
-void AnimatedColorOption::Set(Color a_inactive,
-                              Color a_active,
-                              animation::Duration a_duration,
-                              animation::easing::Function a_function) {
+/// @brief A color option that can be animated.
+/// @params _inactive The color when the component is inactive.
+/// @params _active The color when the component is active.
+/// @params _duration The duration of the animation.
+/// @params _function The easing function of the animation.
+/// @ingroup component
+void AnimatedColorOption::Set(Color _inactive,
+                              Color _active,
+                              animation::Duration _duration,
+                              animation::easing::Function _function) {
   enabled = true;
-  inactive = a_inactive;
-  active = a_active;
-  duration = a_duration;
-  function = std::move(a_function);
+  inactive = _inactive;
+  active = _active;
+  duration = _duration;
+  function = std::move(_function);
 }
 
+/// @brief Set how the underline should animate.
+/// @param d The duration of the animation.
+/// @param f The easing function of the animation.
+/// @ingroup component
 void UnderlineOption::SetAnimation(animation::Duration d,
                                    animation::easing::Function f) {
   SetAnimationDuration(d);
   SetAnimationFunction(std::move(f));
 }
 
+/// @brief Set how the underline should animate.
+/// @param d The duration of the animation.
+/// @ingroup component
 void UnderlineOption::SetAnimationDuration(animation::Duration d) {
   leader_duration = d;
   follower_duration = d;
 }
 
+/// @brief Set how the underline should animate.
+/// @param f The easing function of the animation.
+/// @ingroup component
 void UnderlineOption::SetAnimationFunction(animation::easing::Function f) {
   leader_function = f;
   follower_function = std::move(f);
 }
 
+/// @brief Set how the underline should animate.
+/// This is useful to desynchronize the animation of the leader and the
+/// follower.
+/// @param f_leader The duration of the animation for the leader.
+/// @param f_follower The duration of the animation for the follower.
+/// @ingroup component
 void UnderlineOption::SetAnimationFunction(
     animation::easing::Function f_leader,
     animation::easing::Function f_follower) {
@@ -47,6 +69,9 @@ void UnderlineOption::SetAnimationFunction(
   follower_function = std::move(f_follower);
 }
 
+/// @brief Standard options for an horizontal menu.
+/// This can be useful to implement a tab bar.
+/// @ingroup component
 // static
 MenuOption MenuOption::Horizontal() {
   MenuOption option;
@@ -69,6 +94,9 @@ MenuOption MenuOption::Horizontal() {
   return option;
 }
 
+/// @brief Standard options for an animated horizontal menu.
+/// This can be useful to implement a tab bar.
+/// @ingroup component
 // static
 MenuOption MenuOption::HorizontalAnimated() {
   auto option = Horizontal();
@@ -76,6 +104,9 @@ MenuOption MenuOption::HorizontalAnimated() {
   return option;
 }
 
+/// @brief Standard options for a vertical menu.
+/// This can be useful to implement a list of selectable items.
+/// @ingroup component
 // static
 MenuOption MenuOption::Vertical() {
   MenuOption option;
@@ -95,6 +126,9 @@ MenuOption MenuOption::Vertical() {
   return option;
 }
 
+/// @brief Standard options for an animated vertical menu.
+/// This can be useful to implement a list of selectable items.
+/// @ingroup component
 // static
 MenuOption MenuOption::VerticalAnimated() {
   auto option = MenuOption::Vertical();
@@ -115,6 +149,9 @@ MenuOption MenuOption::VerticalAnimated() {
   return option;
 }
 
+/// @brief Standard options for a horitontal menu with some separator.
+/// This can be useful to implement a tab bar.
+/// @ingroup component
 // static
 MenuOption MenuOption::Toggle() {
   auto option = MenuOption::Horizontal();
@@ -123,6 +160,7 @@ MenuOption MenuOption::Toggle() {
 }
 
 /// @brief Create a ButtonOption, highlighted using [] characters.
+/// @ingroup component
 // static
 ButtonOption ButtonOption::Ascii() {
   ButtonOption option;
@@ -135,6 +173,7 @@ ButtonOption ButtonOption::Ascii() {
 }
 
 /// @brief Create a ButtonOption, inverted when focused.
+/// @ingroup component
 // static
 ButtonOption ButtonOption::Simple() {
   ButtonOption option;
@@ -150,6 +189,7 @@ ButtonOption ButtonOption::Simple() {
 
 /// @brief Create a ButtonOption. The button is shown using a border, inverted
 /// when focused. This is the current default.
+/// @ingroup component
 ButtonOption ButtonOption::Border() {
   ButtonOption option;
   option.transform = [](const EntryState& s) {
@@ -166,6 +206,7 @@ ButtonOption ButtonOption::Border() {
 }
 
 /// @brief Create a ButtonOption, using animated colors.
+/// @ingroup component
 // static
 ButtonOption ButtonOption::Animated() {
   return Animated(Color::Black, Color::GrayLight,  //
@@ -173,6 +214,7 @@ ButtonOption ButtonOption::Animated() {
 }
 
 /// @brief Create a ButtonOption, using animated colors.
+/// @ingroup component
 // static
 ButtonOption ButtonOption::Animated(Color color) {
   return ButtonOption::Animated(
@@ -183,6 +225,7 @@ ButtonOption ButtonOption::Animated(Color color) {
 }
 
 /// @brief Create a ButtonOption, using animated colors.
+/// @ingroup component
 // static
 ButtonOption ButtonOption::Animated(Color background, Color foreground) {
   // NOLINTBEGIN
@@ -195,6 +238,7 @@ ButtonOption ButtonOption::Animated(Color background, Color foreground) {
 }
 
 /// @brief Create a ButtonOption, using animated colors.
+/// @ingroup component
 // static
 ButtonOption ButtonOption::Animated(Color background,
                                     Color foreground,
@@ -214,6 +258,7 @@ ButtonOption ButtonOption::Animated(Color background,
 }
 
 /// @brief Option for standard Checkbox.
+/// @ingroup component
 // static
 CheckboxOption CheckboxOption::Simple() {
   auto option = CheckboxOption();
@@ -238,6 +283,7 @@ CheckboxOption CheckboxOption::Simple() {
 }
 
 /// @brief Option for standard Radiobox
+/// @ingroup component
 // static
 RadioboxOption RadioboxOption::Simple() {
   auto option = RadioboxOption();
@@ -261,6 +307,8 @@ RadioboxOption RadioboxOption::Simple() {
   return option;
 }
 
+/// @brief Standard options for the input component.
+/// @ingroup component
 // static
 InputOption InputOption::Default() {
   InputOption option;
@@ -282,6 +330,8 @@ InputOption InputOption::Default() {
   return option;
 }
 
+/// @brief Standard options for a more beautiful input component.
+/// @ingroup component
 // static
 InputOption InputOption::Spacious() {
   InputOption option;

src/ftxui/component/dropdown.cpp

@@ -15,6 +15,10 @@
 
 namespace ftxui {
 
+/// @brief A dropdown menu.
+/// @ingroup component
+/// @param entries The list of entries to display.
+/// @param selected The index of the selected entry.
 Component Dropdown(ConstStringListRef entries, int* selected) {
   class Impl : public ComponentBase {
    public:

src/ftxui/component/event.cpp

@@ -9,6 +9,9 @@
 
 namespace ftxui {
 
+/// @brief An event corresponding to a given typed character.
+/// @param input The character typed by the user.
+/// @ingroup component
 // static
 Event Event::Character(std::string input) {
   Event event;
@@ -17,16 +20,26 @@ Event Event::Character(std::string input) {
   return event;
 }
 
+/// @brief An event corresponding to a given typed character.
+/// @param c The character typed by the user.
+/// @ingroup component
 // static
 Event Event::Character(char c) {
   return Event::Character(std::string{c});
 }
 
+/// @brief An event corresponding to a given typed character.
+/// @param c The character typed by the user.
+/// @ingroup component
 // static
 Event Event::Character(wchar_t c) {
   return Event::Character(to_string(std::wstring{c}));
 }
 
+/// @brief An event corresponding to a given typed character.
+/// @param input The sequence of character send by the terminal.
+/// @param mouse The mouse state.
+/// @ingroup component
 // static
 Event Event::Mouse(std::string input, struct Mouse mouse) {
   Event event;
@@ -36,6 +49,9 @@ Event Event::Mouse(std::string input, struct Mouse mouse) {
   return event;
 }
 
+/// @brief An custom event whose meaning is defined by the user of the library.
+/// @param input An arbitrary sequence of character defined by the developer.
+/// @ingroup component.
 // static
 Event Event::Special(std::string input) {
   Event event;
@@ -43,6 +59,7 @@ Event Event::Special(std::string input) {
   return event;
 }
 
+/// @internal
 // static
 Event Event::CursorReporting(std::string input, int x, int y) {
   Event event;

src/ftxui/component/loop.cpp

@@ -9,6 +9,14 @@
 
 namespace ftxui {
 
+/// @brief A Loop is a wrapper around a Component and a ScreenInteractive.
+/// It is used to run a Component in a terminal.
+/// @ingroup component
+/// @see Component, ScreenInteractive.
+/// @see ScreenInteractive::Loop().
+/// @see ScreenInteractive::ExitLoop().
+/// @param screen The screen to use.
+/// @param component The component to run.
 // NOLINTNEXTLINE
 Loop::Loop(ScreenInteractive* screen, Component component)
     : screen_(screen), component_(std::move(component)) {
@@ -19,6 +27,8 @@ Loop::~Loop() {
   screen_->PostMain();
 }
 
+/// @brief Whether the loop has quitted.
+/// @ingroup component
 bool Loop::HasQuitted() {
   return screen_->HasQuitted();
 }

src/ftxui/component/maybe.cpp

@@ -14,6 +14,11 @@
 
 namespace ftxui {
 
+/// @brief Decorate a component |child|. It is shown only when |show| returns
+/// true.
+/// @param child the compoenent to decorate.
+/// @param show a function returning whether |child| should shown.
+/// @ingroup component
 Component Maybe(Component child, std::function<bool()> show) {
   class Impl : public ComponentBase {
    public:
@@ -40,7 +45,7 @@ Component Maybe(Component child, std::function<bool()> show) {
 
 /// @brief Decorate a component. It is shown only when the |show| function
 /// returns true.
-/// @param show a function returning whether the decoratorated component should
+/// @param show a function returning whether the decorated component should
 /// be shown.
 /// @ingroup component
 ///

src/ftxui/component/screen_interactive.cpp

@@ -402,6 +402,9 @@ void ScreenInteractive::TrackMouse(bool enable) {
   track_mouse_ = enable;
 }
 
+/// @brief Add a task to the main loop. 
+/// It will be executed later, after every other scheduled tasks.
+/// @ingroup component
 void ScreenInteractive::Post(Task task) {
   // Task/Events sent toward inactive screen or screen waiting to become
   // inactive are dropped.
@@ -412,10 +415,15 @@ void ScreenInteractive::Post(Task task) {
   task_sender_->Send(std::move(task));
 }
 
+/// @brief Add an event to the main loop.
+/// It will be executed later, after every other scheduled events.
+/// @ingroup component
 void ScreenInteractive::PostEvent(Event event) {
   Post(event);
 }
 
+/// @brief Add a task to draw the screen one more time, until all the animations
+/// are done.
 void ScreenInteractive::RequestAnimationFrame() {
   if (animation_requested_) {
     return;
@@ -428,6 +436,10 @@ void ScreenInteractive::RequestAnimationFrame() {
   }
 }
 
+/// @brief Try to get the unique lock about behing able to capture the mouse.
+/// @return A unique lock if the mouse is not already captured, otherwise a
+/// null.
+/// @ingroup component
 CapturedMouse ScreenInteractive::CaptureMouse() {
   if (mouse_captured) {
     return nullptr;
@@ -437,15 +449,21 @@ CapturedMouse ScreenInteractive::CaptureMouse() {
       [this] { mouse_captured = false; });
 }
 
+/// @brief Execute the main loop.
+/// @param component The component to draw.
+/// @ingroup component
 void ScreenInteractive::Loop(Component component) {  // NOLINT
   class Loop loop(this, std::move(component));
   loop.Run();
 }
 
+/// @brief Return whether the main loop has been quit.
+/// @ingroup component
 bool ScreenInteractive::HasQuitted() {
   return task_receiver_->HasQuitted();
 }
 
+// private
 void ScreenInteractive::PreMain() {
   // Suspend previously active screen:
   if (g_active_screen) {
@@ -467,6 +485,7 @@ void ScreenInteractive::PreMain() {
   previous_animation_time_ = animation::Clock::now();
 }
 
+// private
 void ScreenInteractive::PostMain() {
   // Put cursor position at the end of the drawing.
   ResetCursorPosition();
@@ -505,11 +524,13 @@ Closure ScreenInteractive::WithRestoredIO(Closure fn) {  // NOLINT
   };
 }
 
+/// @brief Return the currently active screen, or null if none.
 // static
 ScreenInteractive* ScreenInteractive::Active() {
   return g_active_screen;
 }
 
+// private
 void ScreenInteractive::Install() {
   frame_valid_ = false;
 
@@ -622,6 +643,7 @@ void ScreenInteractive::Install() {
       std::thread(&AnimationListener, &quit_, task_receiver_->MakeSender());
 }
 
+// private
 void ScreenInteractive::Uninstall() {
   ExitNow();
   event_listener_.join();
@@ -629,6 +651,7 @@ void ScreenInteractive::Uninstall() {
   OnExit();
 }
 
+// private
 // NOLINTNEXTLINE
 void ScreenInteractive::RunOnceBlocking(Component component) {
   ExecuteSignalHandlers();
@@ -639,6 +662,7 @@ void ScreenInteractive::RunOnceBlocking(Component component) {
   RunOnce(component);
 }
 
+// private
 void ScreenInteractive::RunOnce(Component component) {
   Task task;
   while (task_receiver_->ReceiveNonBlocking(&task)) {
@@ -648,6 +672,7 @@ void ScreenInteractive::RunOnce(Component component) {
   Draw(std::move(component));
 }
 
+// private
 void ScreenInteractive::HandleTask(Component component, Task& task) {
   // clang-format off
   std::visit([&](auto&& arg) {
@@ -699,6 +724,7 @@ void ScreenInteractive::HandleTask(Component component, Task& task) {
   // clang-format on
 }
 
+// private
 // NOLINTNEXTLINE
 void ScreenInteractive::Draw(Component component) {
   if (frame_valid_) {
@@ -793,24 +819,31 @@ void ScreenInteractive::Draw(Component component) {
   frame_valid_ = true;
 }
 
+// private
 void ScreenInteractive::ResetCursorPosition() {
   std::cout << reset_cursor_position;
   reset_cursor_position = "";
 }
 
+/// @brief Return a function to exit the main loop.
+/// @ingroup component
 Closure ScreenInteractive::ExitLoopClosure() {
   return [this] { Exit(); };
 }
 
+/// @brief Exit the main loop.
+/// @ingroup component
 void ScreenInteractive::Exit() {
   Post([this] { ExitNow(); });
 }
 
+// private:
 void ScreenInteractive::ExitNow() {
   quit_ = true;
   task_sender_.reset();
 }
 
+// private:
 void ScreenInteractive::Signal(int signal) {
   if (signal == SIGABRT) {
     OnExit();

src/ftxui/component/slider.cpp

@@ -34,7 +34,6 @@ Decorator flexDirection(Direction direction) {
   }
   return xflex;  // NOT_REACHED()
 }
-}  // namespace
 
 template <class T>
 class SliderBase : public ComponentBase {
@@ -256,6 +255,7 @@ class SliderWithLabel : public ComponentBase {
   Box box_;
   bool mouse_hover_ = false;
 };
+}  // namespace
 
 /// @brief An horizontal slider.
 /// @param label The name of the slider.