Improve the documentation.

doc/Doxyfile.in

@@ -240,12 +240,6 @@ TAB_SIZE               = 2
 
 ALIASES                =
 
-# This tag can be used to specify a number of word-keyword mappings (TCL only).
-# A mapping has the form "name=value". For example adding "class=itcl::class"
-# will allow you to use the command class in the itcl::class meaning.
-
-TCL_SUBST              =
-
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
 # instance, some of the names that are used will be different. The list of all
@@ -789,7 +783,6 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                 += @CMAKE_CURRENT_SOURCE_DIR@/../tutorial/
 INPUT                 += @CMAKE_CURRENT_SOURCE_DIR@/../include/
 INPUT                 += @CMAKE_CURRENT_SOURCE_DIR@/../src/
 INPUT                 += @CMAKE_CURRENT_SOURCE_DIR@
@@ -2175,12 +2168,6 @@ EXTERNAL_GROUPS        = YES
 
 EXTERNAL_PAGES         = YES
 
-# The PERL_PATH should be the absolute path and name of the perl script
-# interpreter (i.e. the result of 'which perl').
-# The default file (with absolute path) is: /usr/bin/perl.
-
-PERL_PATH              = /usr/bin/perl
-
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
@@ -2194,15 +2181,6 @@ PERL_PATH              = /usr/bin/perl
 
 CLASS_DIAGRAMS         = YES
 
-# You can define message sequence charts within doxygen comments using the \msc
-# command. Doxygen will then run the mscgen tool (see:
-# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the
-# documentation. The MSCGEN_PATH tag allows you to specify the directory where
-# the mscgen tool resides. If left empty the tool is assumed to be found in the
-# default search path.
-
-MSCGEN_PATH            =
-
 # You can include diagrams made with dia in doxygen documentation. Doxygen will
 # then run dia to produce the diagram and insert it in the documentation. The
 # DIA_PATH tag allows you to specify the directory where the dia binary resides.

doc/example_list.h

@@ -1,43 +0,0 @@
-/// @example ./examples/util/print_key_press.cpp
-/// @example ./examples/dom/color_truecolor_HSV.cpp
-/// @example ./examples/dom/dbox.cpp
-/// @example ./examples/dom/separator.cpp
-/// @example ./examples/dom/style_color.cpp
-/// @example ./examples/dom/color_info_palette256.cpp
-/// @example ./examples/dom/color_truecolor_RGB.cpp
-/// @example ./examples/dom/paragraph.cpp
-/// @example ./examples/dom/style_blink.cpp
-/// @example ./examples/dom/style_dim.cpp
-/// @example ./examples/dom/style_inverted.cpp
-/// @example ./examples/dom/graph.cpp
-/// @example ./examples/dom/package_manager.cpp
-/// @example ./examples/dom/window.cpp
-/// @example ./examples/dom/html_like.cpp
-/// @example ./examples/dom/border.cpp
-/// @example ./examples/dom/style_underlined.cpp
-/// @example ./examples/dom/color_gallery.cpp
-/// @example ./examples/dom/gauge.cpp
-/// @example ./examples/dom/style_bold.cpp
-/// @example ./examples/dom/spinner.cpp
-/// @example ./examples/dom/style_gallery.cpp
-/// @example ./examples/dom/vbox_hbox.cpp
-/// @example ./examples/dom/size.cpp
-/// @example ./examples/dom/hflow.cpp
-/// @example ./examples/component/tab_vertical.cpp
-/// @example ./examples/component/gallery.cpp
-/// @example ./examples/component/checkbox.cpp
-/// @example ./examples/component/checkbox_in_frame.cpp
-/// @example ./examples/component/menu2.cpp
-/// @example ./examples/component/tab_horizontal.cpp
-/// @example ./examples/component/slider.cpp
-/// @example ./examples/component/slider_rgb.cpp
-/// @example ./examples/component/input.cpp
-/// @example ./examples/component/homescreen.cpp
-/// @example ./examples/component/radiobox.cpp
-/// @example ./examples/component/resizable_split.cpp
-/// @example ./examples/component/menu.cpp
-/// @example ./examples/component/menu_style.cpp
-/// @example ./examples/component/radiobox_in_frame.cpp
-/// @example ./examples/component/button.cpp
-/// @example ./examples/component/toggle.cpp
-/// @example ./examples/component/modal_dialog.cpp

examples/dom/color_gallery.cpp

@@ -1,16 +1,16 @@
-#include <ftxui/dom/elements.hpp>
-#include <ftxui/screen/color_info.hpp>
-#include <ftxui/screen/screen.hpp>
-#include <ftxui/screen/terminal.hpp>
-#include <memory>
-#include <utility>
-#include <vector>
+#include <ftxui/screen/color_info.hpp>  // for ColorInfo
+#include <ftxui/screen/screen.hpp>      // for Dimension, Screen
+#include <ftxui/screen/terminal.hpp>  // for Terminal, Terminal::Color, Terminal::Palette16, Terminal::Palette256, Terminal::TrueColor
+#include <memory>                     // for allocator, shared_ptr
+#include <utility>                    // for move
+#include <vector>                     // for vector
 
 using namespace ftxui;
-#include "./color_info_sorted_2d.ipp"  // ColorInfoSorted2D.
-#include "ftxui/dom/node.hpp"
-#include "ftxui/screen/box.hpp"
-#include "ftxui/screen/color.hpp"
+#include "./color_info_sorted_2d.ipp"  // for ColorInfoSorted2D
+#include "ftxui/dom/elements.hpp"  // for text, bgcolor, color, vbox, hbox, separator, operator|, Elements, Element, border
+#include "ftxui/dom/node.hpp"      // for Render
+#include "ftxui/screen/box.hpp"    // for ftxui
+#include "ftxui/screen/color.hpp"  // for Color, Color::Black, Color::Blue, Color::BlueLight, Color::Cyan, Color::CyanLight, Color::Default, Color::GrayDark, Color::GrayLight, Color::Green, Color::GreenLight, Color::Magenta, Color::MagentaLight, Color::Red, Color::RedLight, Color::White, Color::Yellow, Color::YellowLight, Color::Palette256
 
 int main(int argc, const char* argv[]) {
   // clang-format off

examples/dom/html_like.cpp

@@ -1,11 +1,11 @@
-#include <chrono>                  // for operator""s, chrono_literals
-#include <ftxui/dom/elements.hpp>  // for paragraph, text, operator|, Element, border, color, hflow, spinner, vbox, bold, dim, underlined
+#include <chrono>                   // for operator""s, chrono_literals
 #include <ftxui/screen/screen.hpp>  // for Screen, Dimension
 #include <iostream>                 // for cout, ostream
-#include <memory>                   // for shared_ptr
-#include <string>                   // for allocator, operator<<, string
+#include <memory>                   // for allocator, shared_ptr
+#include <string>                   // for operator<<, string
 #include <thread>                   // for sleep_for
 
+#include "ftxui/dom/elements.hpp"  // for paragraph, text, operator|, Element, border, color, hflow, spinner, vbox, bold, dim, underlined
 #include "ftxui/dom/node.hpp"      // for Render
 #include "ftxui/screen/box.hpp"    // for ftxui
 #include "ftxui/screen/color.hpp"  // for Color, Color::Red

examples/dom/style_color.cpp

@@ -1,10 +1,10 @@
-#include <ftxui/dom/elements.hpp>
-#include <ftxui/screen/screen.hpp>
-#include <memory>
+#include <ftxui/screen/screen.hpp>  // for Dimension, Screen
+#include <memory>                   // for allocator
 
-#include "ftxui/dom/node.hpp"
-#include "ftxui/screen/box.hpp"
-#include "ftxui/screen/color.hpp"
+#include "ftxui/dom/elements.hpp"  // for text, bgcolor, color, vbox, filler, hbox
+#include "ftxui/dom/node.hpp"      // for Render
+#include "ftxui/screen/box.hpp"    // for ftxui
+#include "ftxui/screen/color.hpp"  // for Color, Color::Black, Color::Blue, Color::BlueLight, Color::Cyan, Color::CyanLight, Color::Default, Color::GrayDark, Color::GrayLight, Color::Green, Color::GreenLight, Color::Magenta, Color::MagentaLight, Color::Red, Color::RedLight, Color::White, Color::Yellow, Color::YellowLight
 
 int main(int argc, const char* argv[]) {
   using namespace ftxui;

include/ftxui/component/component.hpp

@@ -50,6 +50,10 @@ Component Toggle(const std::vector<std::wstring>* entries,
                  Ref<ToggleOption> option = {});
 template <class T>  // T = {int, float, long}
 Component Slider(StringRef label, T* value, T min, T max, T increment);
+Component ResizableSplitLeft(Component main, Component back, int* main_size);
+Component ResizableSplitRight(Component main, Component back, int* main_size);
+Component ResizableSplitTop(Component main, Component back, int* main_size);
+Component ResizableSplitBottom(Component main, Component back, int* main_size);
 Component Renderer(Component child, std::function<Element()>);
 Component Renderer(std::function<Element()>);
 Component CatchEvent(Component child, std::function<bool(Event)>);
@@ -63,11 +67,6 @@ Component Tab(Components children, int* selector);
 
 }  // namespace Container
 
-Component ResizableSplitLeft(Component main, Component back, int* main_size);
-Component ResizableSplitRight(Component main, Component back, int* main_size);
-Component ResizableSplitTop(Component main, Component back, int* main_size);
-Component ResizableSplitBottom(Component main, Component back, int* main_size);
-
 }  // namespace ftxui
 
 #endif /* end of include guard: FTXUI_COMPONENT_HPP */

include/ftxui/component/component_options.hpp

@@ -7,6 +7,7 @@
 namespace ftxui {
 
 /// @brief Option for the Menu component.
+/// @ingroup component
 struct MenuOption {
   Decorator style_normal = nothing;    /// style.
   Decorator style_focused = inverted;  /// Style when focused.
@@ -23,12 +24,14 @@ struct MenuOption {
 };
 
 /// @brief Option for the Button component.
+/// @ingroup component
 struct ButtonOption {
   /// Whether to show a border around the button.
   bool border = true;
 };
 
 /// @brief Option for the Checkbox component.
+/// @ingroup component
 struct CheckboxOption {
   std::wstring style_checked = L"▣ ";    /// Prefix for a "checked" state.
   std::wstring style_unchecked = L"☐ ";  /// Prefix for a "unchecked" state.
@@ -40,6 +43,7 @@ struct CheckboxOption {
 };
 
 /// @brief Option for the Input component.
+/// @ingroup component
 struct InputOption {
   /// Called when the content changes.
   std::function<void()> on_change = [] {};
@@ -50,6 +54,7 @@ struct InputOption {
 };
 
 /// @brief Option for the Radiobox component.
+/// @ingroup component
 struct RadioboxOption {
   std::wstring style_checked = L"◉ ";    /// Prefix for a "checked" state.
   std::wstring style_unchecked = L"○ ";  /// Prefix for a "unchecked" state.
@@ -63,6 +68,7 @@ struct RadioboxOption {
 };
 
 /// @brief Option for the Toggle component.
+/// @ingroup component
 struct ToggleOption {
   Decorator style_normal = nothing;    /// style.
   Decorator style_focused = inverted;  /// Style when focused.
@@ -78,7 +84,7 @@ struct ToggleOption {
   Ref<int> focused_entry = 0;
 };
 
-};  // namespace ftxui
+}  // namespace ftxui
 
 #endif /* end of include guard: FTXUI_COMPONENT_COMPONENT_OPTIONS_HPP */
 

include/ftxui/dom/elements.hpp

@@ -102,15 +102,11 @@ Element nothing(Element element);
 // combinaison with dbox.
 Element clear_under(Element element);
 
-// Make container able to take any number of children as input.
-#include "take_any_args.hpp"
-TAKE_ANY_ARGS(vbox)
-TAKE_ANY_ARGS(hbox)
-TAKE_ANY_ARGS(dbox)
-TAKE_ANY_ARGS(hflow)
-
 }  // namespace ftxui
 
+// Make container able to take any number of children as input.
+#include "ftxui/dom/take_any_args.hpp"
+
 #endif /* end of include guard: FTXUI_DOM_ELEMENTS_HPP */
 
 // Copyright 2020 Arthur Sonzogni. All rights reserved.

include/ftxui/dom/take_any_args.hpp

@@ -1,6 +1,8 @@
 // IWYU pragma: private, include "ftxui/dom/elements.hpp"
 #include <type_traits>
 
+namespace ftxui {
+
 template <class T>
 void Merge(Elements&, T) {}
 
@@ -30,6 +32,12 @@ Elements unpack(Args... args) {
     return container(unpack(std::forward<Args>(children)...)); \
   }
 
+TAKE_ANY_ARGS(vbox)
+TAKE_ANY_ARGS(hbox)
+TAKE_ANY_ARGS(dbox)
+TAKE_ANY_ARGS(hflow)
+}  // namespace ftxui
+
 // Copyright 2020 Arthur Sonzogni. All rights reserved.
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.

src/ftxui/component/button.cpp

@@ -16,8 +16,6 @@
 namespace ftxui {
 
 namespace {
-/// @brief A button. An action is associated to the click event.
-/// @ingroup dom
 class ButtonBase : public ComponentBase {
  public:
   ButtonBase(ConstStringRef label,
@@ -69,6 +67,7 @@ class ButtonBase : public ComponentBase {
 /// @brief Draw a button. Execute a function when clicked.
 /// @param label The label of the button.
 /// @param on_click The action to execute when clicked.
+/// @param option Additional optional parameters.
 /// @ingroup component
 /// @see ButtonBase
 ///

src/ftxui/component/catch_event.cpp

@@ -8,8 +8,6 @@
 
 namespace ftxui {
 
-/// @brief A component executing a provided function for catching events.
-/// @ingroup component.
 class CatchEventBase : public ComponentBase {
  public:
   // Constructor.
@@ -31,6 +29,7 @@ class CatchEventBase : public ComponentBase {
 
 /// @brief Return a component, using |on_event| to catch events. This function
 /// must returns true when the event has been handled, false otherwise.
+/// @param child The wrapped component.
 /// @param on_event The function drawing the interface.
 /// @ingroup component
 ///

src/ftxui/component/checkbox.cpp

@@ -15,9 +15,6 @@
 namespace ftxui {
 
 namespace {
-/// @brief A Checkbox. It can be checked or unchecked.Display an element on a
-/// ftxui::Screen.
-/// @ingroup dom
 class CheckboxBase : public ComponentBase {
  public:
   CheckboxBase(ConstStringRef label, bool* state, Ref<CheckboxOption> option)
@@ -25,10 +22,10 @@ class CheckboxBase : public ComponentBase {
 #if defined(FTXUI_MICROSOFT_TERMINAL_FALLBACK)
     // Microsoft terminal do not use fonts able to render properly the default
     // radiobox glyph.
-    if (option->checked == L"▣ ")
-      option->checked = L"[X]";
-    if (option->unchecked == L"☐ ")
-      option->unchecked = L"[ ]";
+    if (option_->style_checked == L"▣ ")
+      option_->style_checked = L"[X]";
+    if (option_->style_unchecked == L"☐ ")
+      option_->style_unchecked = L"[ ]";
 #endif
   }
 
@@ -86,6 +83,7 @@ class CheckboxBase : public ComponentBase {
 /// @brief Draw checkable element.
 /// @param label The label of the checkbox.
 /// @param checked Whether the checkbox is checked or not.
+/// @param option Additional optional parameters.
 /// @ingroup component
 /// @see CheckboxBase
 ///

src/ftxui/component/component.cpp

@@ -96,12 +96,12 @@ bool ComponentBase::Focused() {
 }
 
 /// @brief Make the |child| to be the "active" one.
-/// @argument child the child to become active.
+/// @param child the child to become active.
 /// @ingroup component
 void ComponentBase::SetActiveChild(ComponentBase*) {}
 
 /// @brief Make the |child| to be the "active" one.
-/// @argument child the child to become active.
+/// @param child the child to become active.
 /// @ingroup component
 void ComponentBase::SetActiveChild(Component child) {
   SetActiveChild(child.get());
@@ -121,7 +121,7 @@ void ComponentBase::TakeFocus() {
 
 /// @brief Take the CapturedMouse if available. There is only one component of
 /// them. It represents a component taking priority over others.
-/// @argument event
+/// @param event
 /// @ingroup component
 CapturedMouse ComponentBase::CaptureMouse(const Event& event) {
   if (!event.screen_)

src/ftxui/component/container.cpp

@@ -11,7 +11,6 @@
 
 namespace ftxui {
 
-/// @brief A component where focus and events are automatically handled for you.
 class ContainerBase : public ComponentBase {
  public:
   static Component Vertical() { return Vertical({}); }
@@ -195,7 +194,7 @@ Component Vertical(Components children) {
 /// vertically using up/down arrow key or 'j'/'k' keys.
 /// This is useful for implementing a Menu for instance.
 /// @param children the list of components.
-/// @param selector An integer storing the selected children.
+/// @param selector A reference to the index of the selected children.
 /// @ingroup component
 /// @see ContainerBase
 ///
@@ -237,6 +236,7 @@ Component Horizontal(Components children) {
 /// @brief A list of components, drawn one by one horizontally and navigated
 /// horizontally using left/right arrow key or 'h'/'l' keys.
 /// @param children the list of components.
+/// @param selector A reference to the index of the selected children.
 /// @ingroup component
 /// @see ContainerBase
 ///
@@ -259,7 +259,7 @@ Component Horizontal(Components children, int* selector) {
 /// a time. The |selector| gives the index of the selected component. This is
 /// useful to implement tabs.
 /// @param selector The index of the drawn children.
-/// @param children the list of components.
+/// @param children The list of components.
 /// @ingroup component
 /// @see ContainerBase
 ///

src/ftxui/component/input.cpp

@@ -17,8 +17,7 @@
 
 namespace ftxui {
 
-/// @brief An input box. The user can type text into it.
-/// @ingroup component.
+// An input box. The user can type text into it.
 class InputBase : public ComponentBase {
  public:
   InputBase(StringRef content,
@@ -171,6 +170,7 @@ class InputBase : public ComponentBase {
 /// @brief An input box for editing text.
 /// @param content The editable content.
 /// @param placeholder The text displayed when content is still empty.
+/// @param option Additional optional parameters.
 /// @ingroup component
 /// @see InputBase
 ///

src/ftxui/component/menu.cpp

@@ -119,6 +119,7 @@ class MenuBase : public ComponentBase {
 /// @brief A list of text. The focused element is selected.
 /// @param entries The list of entries in the menu.
 /// @param selected The index of the currently selected element.
+/// @param option Additional optional parameters.
 /// @ingroup component
 /// @see MenuBase
 ///

src/ftxui/component/radiobox.cpp

@@ -32,10 +32,10 @@ class RadioboxBase : public ComponentBase {
 #if defined(FTXUI_MICROSOFT_TERMINAL_FALLBACK)
     // Microsoft terminal do not use fonts able to render properly the default
     // radiobox glyph.
-    if (option_->checked == L"◉ ")
-      option_->checked = L"(*)";
-    if (option_->unchecked == L"○ ")
-      option_->unchecked = L"( )";
+    if (option_->style_checked == L"◉ ")
+      option_->style_checked = L"(*)";
+    if (option_->style_unchecked == L"○ ")
+      option_->style_unchecked = L"( )";
 #endif
   }
   ~RadioboxBase() override = default;
@@ -135,6 +135,7 @@ class RadioboxBase : public ComponentBase {
 /// @brief A list of element, where only one can be selected.
 /// @param entries The list of entries in the list.
 /// @param selected The index of the currently selected element.
+/// @param option Additional optional parameters.
 /// @ingroup component
 /// @see RadioboxBase
 ///

src/ftxui/component/renderer.cpp

@@ -8,8 +8,7 @@
 
 namespace ftxui {
 
-/// @brief A component rendering Element from a function.
-/// @ingroup component.
+// @brief A component rendering Element from a function.
 class RendererBase : public ComponentBase {
  public:
   // Access this interface from a Component

src/ftxui/component/toggle.cpp

@@ -121,6 +121,9 @@ class ToggleBase : public ComponentBase {
 }  // namespace
 
 /// @brief An horizontal list of elements. The user can navigate through them.
+/// @param entries The list of selectable entries to display.
+/// @param selected Reference the selected entry.
+/// @param option Additional optional parameters.
 /// @ingroup component
 Component Toggle(const std::vector<std::wstring>* entries,
                  int* selected,

src/ftxui/dom/composite_decorator.cpp

@@ -6,7 +6,7 @@
 namespace ftxui {
 
 /// @brief Center an element horizontally.
-/// @param The input element.
+/// @param child The decorated element.
 /// @return The centered element.
 /// @ingroup dom
 Element hcenter(Element child) {
@@ -14,7 +14,7 @@ Element hcenter(Element child) {
 }
 
 /// @brief Center an element vertically.
-/// @param The input element.
+/// @param child The decorated element.
 /// @return The centered element.
 /// @ingroup dom
 Element vcenter(Element child) {
@@ -22,7 +22,7 @@ Element vcenter(Element child) {
 }
 
 /// @brief Center an element horizontally and vertically.
-/// @param The input element.
+/// @param child The decorated element.
 /// @return The centered element.
 /// @ingroup dom
 Element center(Element child) {
@@ -30,7 +30,7 @@ Element center(Element child) {
 }
 
 /// @brief Align an element on the right side.
-/// @param The input element.
+/// @param child The decorated element.
 /// @return The right aligned element.
 /// @ingroup dom
 Element align_right(Element child) {

src/ftxui/dom/size.cpp

@@ -82,8 +82,8 @@ class Size : public Node {
 /// @brief Apply a constraint on the size of an element.
 /// @param direction Whether the WIDTH of the HEIGHT of the element must be
 ///                  constrained.
-/// @param constrain The type of constaint.
-/// @param value the value.
+/// @param constraint The type of constaint.
+/// @param value The value.
 /// @ingroup dom
 Decorator size(Direction direction, Constraint constraint, int value) {
   return [=](Element e) {

src/ftxui/dom/util.cpp

@@ -6,11 +6,13 @@
 
 namespace ftxui {
 
+namespace {
 Decorator compose(Decorator a, Decorator b) {
   return [a = std::move(a), b = std::move(b)](Element element) {
     return b(a(std::move(element)));
   };
 }
+}  // namespace
 
 /// @brief A decoration doing absolutely nothing.
 /// @ingroup dom

src/ftxui/screen/color.cpp

@@ -117,9 +117,9 @@ Color Color::RGB(uint8_t red, uint8_t green, uint8_t blue) {
 /// @brief Build a Color from its HSV representation.
 /// https://en.wikipedia.org/wiki/HSL_and_HSV
 ///
-/// @param hue The hue of the color [0,255]
-/// @param saturation The "colorfulness" [0,255].
-/// @param value The "Lightness" [0,255]
+/// @param h The hue of the color [0,255]
+/// @param s The "colorfulness" [0,255].
+/// @param v The "Lightness" [0,255]
 /// @ingroup screen
 // static
 Color Color::HSV(uint8_t h, uint8_t s, uint8_t v) {