Update document WIP.

src/ftxui/component/screen_interactive.cpp

@@ -24,7 +24,7 @@
   #ifndef NOMINMAX
     #define NOMINMAX
   #endif
-  #include <Windows.h> 
+  #include <Windows.h>
   #ifndef UNICODE
     #error Must be compiled in UNICODE mode
   #endif

src/ftxui/dom/blink.cpp

@@ -22,6 +22,8 @@ class Blink : public NodeDecorator {
   }
 };
 
+/// @brief The text drawn alternate in between visible and hidden.
+/// @ingroup dom
 Element blink(Element child) {
   return std::make_shared<Blink>(unpack(std::move(child)));
 }

src/ftxui/dom/bold.cpp

@@ -22,6 +22,8 @@ class Bold : public NodeDecorator {
   }
 };
 
+/// @brief Use a bold font, for elements with more emphasis.
+/// @ingroup dom
 Element bold(Element child) {
   return std::make_shared<Bold>(unpack(std::move(child)));
 }

src/ftxui/dom/border.cpp

@@ -1,7 +1,6 @@
 // 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.
-
 #include <algorithm>
 
 #include "ftxui/dom/elements.hpp"
@@ -104,15 +103,60 @@ class Border : public Node {
     }
   }
 };
-
+/// @brief Draw a border around the element.
+/// @ingroup dom
+///
+/// Add a border around an element
+///
+/// ### Example
+///
+/// ```cpp
+/// // Use 'border' as a function...
+/// Element document = border(text(L"The element"));
+///
+/// // ...Or as a 'pipe'.
+/// Element document = text(L"The element") | border;
+/// ```
+///
+/// ### Output
+///
+/// ```bash
+/// ┌───────────┐
+/// │The element│
+/// └───────────┘
+/// ```
 Element border(Element child) {
   return std::make_shared<Border>(unpack(std::move(child)));
 }
 
+/// @brief Draw window with a title and a border around the element.
+/// @param title The title of the window.
+/// @param content The element to be wrapped.
+/// @ingroup dom
+/// @seealso border
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = window(text(L"Title"),
+///                           text(L"content")
+///                    );
+/// ```
+///
+/// ### Output
+///
+/// ```bash
+/// ┌Title──┐
+/// │content│
+/// └───────┘
+/// ```
 Element window(Element title, Element content) {
   return std::make_shared<Border>(unpack(std::move(content), std::move(title)));
 }
 
+/// @brief Same as border but with a constant Pixel around the element.
+/// @ingroup dom
+/// @seealso border
 Decorator borderWith(Pixel pixel) {
   return [pixel](Element child) {
     return std::make_shared<Border>(unpack(std::move(child)), pixel);

src/ftxui/dom/color.cpp

@@ -42,18 +42,60 @@ class FgColor : public NodeDecorator {
   Color color_;
 };
 
-Element color(Color c, Element child) {
-  return std::make_shared<FgColor>(unpack(std::move(child)), c);
+/// @brief Set the foreground color of an element.
+/// @param The color of the output element.
+/// @param The input element.
+/// @return The output element colored.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = color(Color::Green, text(L"Success")),
+/// ```
+Element color(Color color, Element child) {
+  return std::make_shared<FgColor>(unpack(std::move(child)), color);
 }
 
-Element bgcolor(Color c, Element child) {
-  return std::make_shared<BgColor>(unpack(std::move(child)), c);
+/// @brief Set the background color of an element.
+/// @param The color of the output element.
+/// @param The input element.
+/// @return The output element colored.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = bgcolor(Color::Green, text(L"Success")),
+/// ```
+Element bgcolor(Color color, Element child) {
+  return std::make_shared<BgColor>(unpack(std::move(child)), color);
 }
 
+/// @brief Decorate using a foreground color.
+/// @param c The foreground color to be applied.
+/// @return The Decorator applying the color.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = text(L"red") | color(Color::Red);
+/// ```
 Decorator color(Color c) {
   return [c](Element child) { return color(c, std::move(child)); };
 }
 
+/// @brief Decorate using a background color.
+/// @param The background color to be applied.
+/// @return The Decorator applying the color.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = text(L"red") | bgcolor(Color::Red);
+/// ```
 Decorator bgcolor(Color c) {
   return [c](Element child) { return bgcolor(c, std::move(child)); };
 }

src/ftxui/dom/composite_decorator.cpp

@@ -7,18 +7,34 @@
 
 namespace ftxui {
 
+/// @brief Center an element horizontally.
+/// @param The input element.
+/// @return The centered element.
+/// @ingroup dom
 Element hcenter(Element child) {
   return hbox(filler(), std::move(child), filler()) | xflex_grow;
 }
 
+/// @brief Center an element vertically.
+/// @param The input element.
+/// @return The centered element.
+/// @ingroup dom
 Element vcenter(Element child) {
   return vbox(filler(), std::move(child), filler()) | yflex_grow;
 }
 
+/// @brief Center an element horizontally and vertically.
+/// @param The input element.
+/// @return The centered element.
+/// @ingroup dom
 Element center(Element child) {
   return hcenter(vcenter(std::move(child))) | flex_grow;
 }
 
+/// @brief Align an element on the right side.
+/// @param The input element.
+/// @return The right aligned element.
+/// @ingroup dom
 Element align_right(Element child) {
   return hbox(filler(), std::move(child)) | flex_grow;
 }

src/ftxui/dom/dbox.cpp

@@ -43,6 +43,10 @@ class DBox : public Node {
   }
 };
 
+/// @brief Stack several element on top of each other.
+/// @param The input element.
+/// @return The right aligned element.
+/// @ingroup dom
 Element dbox(Elements children) {
   return std::make_shared<DBox>(std::move(children));
 }

src/ftxui/dom/dim.cpp

@@ -24,6 +24,8 @@ class Dim : public NodeDecorator {
   }
 };
 
+/// @brief Use a light font, for elements with less emphasis.
+/// @ingroup dom
 Element dim(Element child) {
   return std::make_shared<Dim>(unpack(std::move(child)));
 }

src/ftxui/dom/flex.cpp

@@ -83,10 +83,33 @@ class Flex : public Node {
   FlexFunction f_;
 };
 
+/// @brief An element that will take expand proportionnally to the space left in
+/// a container.
+/// @ingroup dom
 Element filler() {
   return std::make_shared<Flex>(function_flex);
 }
 
+/// @brief Make a child element to expand proportionnally to the space left in a
+/// container.
+///
+/// #### Examples:
+///
+/// ~~~cpp
+///   hbox({
+///     text(L"left") | border ,
+///     text(L"middle") | border | flex,
+///     text(L"right") | border,
+///   });
+/// ~~~
+///
+/// #### Output:
+///
+/// ~~~bash
+/// ┌────┐┌─────────────────────────────────────────────────────────┐┌─────┐
+/// │left││middle                                                   ││right│
+/// └────┘└─────────────────────────────────────────────────────────┘└─────┘
+/// ~~~
 Element flex(Element child) {
   return std::make_shared<Flex>(function_flex, std::move(child));
 }

src/ftxui/dom/frame.cpp

@@ -63,7 +63,8 @@ Element focus(Element child) {
 
 class Frame : public Node {
  public:
-  Frame(std::vector<Element> children, bool x_frame, bool y_frame) : Node(std::move(children)), x_frame_(x_frame), y_frame_(y_frame) {}
+  Frame(std::vector<Element> children, bool x_frame, bool y_frame)
+      : Node(std::move(children)), x_frame_(x_frame), y_frame_(y_frame) {}
 
   void ComputeRequirement() override {
     Node::ComputeRequirement();
@@ -109,6 +110,10 @@ class Frame : public Node {
   bool y_frame_;
 };
 
+/// @brief Allow an element to be displayed inside a 'virtual' area. It size can
+/// be larger than its container. In this case only a smaller portion is
+/// displayed. The view is scrollable to make the focused element visible.
+/// @seealso focus
 Element frame(Element child) {
   return std::make_shared<Frame>(unpack(std::move(child)), true, true);
 }

src/ftxui/dom/gauge.cpp

@@ -39,6 +39,24 @@ class Gauge : public Node {
   float progress_;
 };
 
+/// @brief Draw a high definition progress bar.
+/// @param progress The proportion of the area to be filled. Belong to [0,1].
+/// @ingroup dom
+///
+/// ### Example
+///
+/// A gauge. It can be used to represent a progress bar.
+/// ~~~cpp
+/// border(gauge(0.5))
+/// ~~~
+///
+/// #### Output
+///
+/// ~~~bash
+/// ┌──────────────────────────────────────────────────────────────────────────┐
+/// │█████████████████████████████████████                                     │
+/// └──────────────────────────────────────────────────────────────────────────┘
+/// ~~~
 Element gauge(float progress) {
   return std::make_shared<Gauge>(progress);
 }

src/ftxui/dom/graph.cpp

@@ -44,6 +44,8 @@ class Graph : public Node {
   GraphFunction graph_function_;
 };
 
+/// @brief Draw a graph using a GraphFunction.
+/// @param graph_function the function to be called to get the data.
 Element graph(GraphFunction graph_function) {
   return std::make_shared<Graph>(graph_function);
 }

src/ftxui/dom/hbox.cpp

@@ -128,6 +128,18 @@ class HBox : public Node {
   }
 };
 
+/// @brief A container displaying elements horizontally one by one.
+/// @param children The elements in the container
+/// @return The container.
+///
+/// #### Example
+///
+/// ```cpp
+/// hbox({
+///   text(L"Left"),
+///   text(L"Right"),
+/// });
+/// ```
 Element hbox(Elements children) {
   return std::make_shared<HBox>(std::move(children));
 }

src/ftxui/dom/hflow.cpp

@@ -60,6 +60,18 @@ class HFlow : public Node {
   }
 };
 
+/// @brief A container displaying elements horizontally one by one.
+/// @param children The elements in the container
+/// @return The container.
+///
+/// #### Example
+///
+/// ```cpp
+/// hbox({
+///   text(L"Left"),
+///   text(L"Right"),
+/// });
+/// ```
 Element hflow(Elements children) {
   return std::make_shared<HFlow>(std::move(children));
 }

src/ftxui/dom/text.cpp

@@ -2,9 +2,9 @@
 // Use of this source code is governed by the MIT license that can be found in
 // the LICENSE file.
 
+#include <algorithm>
 #include "ftxui/dom/node.hpp"
 #include "ftxui/screen/string.hpp"
-#include <algorithm>
 
 namespace ftxui {
 

src/ftxui/dom/vbox.cpp

@@ -129,6 +129,18 @@ class VBox : public Node {
   }
 };
 
+/// @brief A container displaying elements vertically one by one.
+/// @param children The elements in the container
+/// @return The container.
+///
+/// #### Example
+///
+/// ```cpp
+/// vbox({
+///   text(L"Up"),
+///   text(L"Down"),
+/// });
+/// ```
 Element vbox(Elements children) {
   return std::make_shared<VBox>(std::move(children));
 }

src/ftxui/screen/screen.cpp

@@ -73,28 +73,33 @@ void WindowsEmulateVT100Terminal() {
 
 }  // namespace
 
+/// A fixed dimension.
 Dimension Dimension::Fixed(int v) {
   return Dimension{v, v};
 }
 
-Dimension Dimension::Fit(std::shared_ptr<Node>& e) {
+/// The minimal dimension that will fit the given element.
+Dimension Dimension::Fit(Element& e) {
   e->ComputeRequirement();
   Terminal::Dimensions size = Terminal::Size();
   return Dimension{std::min(e->requirement().min_x, size.dimx),
                    std::min(e->requirement().min_y, size.dimy)};
 }
 
+/// Use the terminal dimensions.
 Dimension Dimension::Full() {
   Terminal::Dimensions size = Terminal::Size();
   return Dimension{size.dimx, size.dimy};
 }
 
 // static
+/// Create a screen with the given dimension along the x-axis and y-axis.
 Screen Screen::Create(Dimension width, Dimension height) {
   return Screen(width.dimx, height.dimy);
 }
 
 // static
+/// Create a screen with the given dimension.
 Screen Screen::Create(Dimension dimension) {
   return Screen(dimension.dimx, dimension.dimy);
 }
@@ -144,6 +149,7 @@ void UpdatePixelStyle(std::wstringstream& ss, Pixel& previous, Pixel& next) {
   previous = next;
 }
 
+/// Produce a std::string that can be used to print the Screen on the terminal.
 std::string Screen::ToString() {
   std::wstringstream ss;
 
@@ -167,14 +173,39 @@ std::string Screen::ToString() {
   return to_string(ss.str());
 }
 
+/// @brief Access a character a given position.
+/// @param x The character position along the x-axis.
+/// @param y The character position along the y-axis.
 wchar_t& Screen::at(int x, int y) {
   return PixelAt(x, y).character;
 }
 
+/// @brief Access a Pixel at a given position.
+/// @param x The pixel position along the x-axis.
+/// @param y The pixel position along the y-axis.
 Pixel& Screen::PixelAt(int x, int y) {
   return In(stencil, x, y) ? pixels_[y][x] : dev_null_pixel;
 }
 
+/// @brief Return a string to be printed in order to reset the cursor position
+///        to the beginning of the screen.
+///
+/// ```cpp
+/// std::string reset_position;
+/// while(true) {
+///   auto document = render();
+///   auto screen = Screen::Create(Dimension::Full(), Dimension::Fit(document));
+///   Render(screen, document);
+///   std::cout << reset_position << screen.ToString() << std::flush;
+///   reset_position = screen.ResetPosition();
+///
+///   using namespace std::chrono_literals;
+///   std::this_thread::sleep_for(0.01s);
+/// }
+/// ```
+///
+/// @return The string to print in order to reset the cursor position to the
+///         beginning.
 std::string Screen::ResetPosition() {
   std::stringstream ss;
   ss << MOVE_LEFT << CLEAR_LINE;
@@ -184,6 +215,7 @@ std::string Screen::ResetPosition() {
   return ss.str();
 }
 
+/// @brief Clear all the pixel from the screen.
 void Screen::Clear() {
   pixels_ = std::vector<std::vector<Pixel>>(dimy_,
                                             std::vector<Pixel>(dimx_, Pixel()));