Update document WIP.

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));
 }