Add more documentation.

src/ftxui/dom/blink.cpp

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

src/ftxui/dom/border.cpp

@@ -129,7 +129,7 @@ Element border(Element child) {
 /// @param title The title of the window.
 /// @param content The element to be wrapped.
 /// @ingroup dom
-/// @seealso border
+/// @see border
 ///
 /// ### Example
 ///
@@ -152,7 +152,7 @@ Element window(Element title, Element content) {
 
 /// @brief Same as border but with a constant Pixel around the element.
 /// @ingroup dom
-/// @seealso border
+/// @see border
 Decorator borderWith(Pixel pixel) {
   return [pixel](Element child) {
     return std::make_shared<Border>(unpack(std::move(child)), pixel);

src/ftxui/dom/color.cpp

@@ -39,8 +39,8 @@ class FgColor : public NodeDecorator {
 };
 
 /// @brief Set the foreground color of an element.
-/// @param The color of the output element.
-/// @param The input element.
+/// @param color The color of the output element.
+/// @param child The input element.
 /// @return The output element colored.
 /// @ingroup dom
 ///
@@ -54,8 +54,8 @@ Element color(Color color, Element child) {
 }
 
 /// @brief Set the background color of an element.
-/// @param The color of the output element.
-/// @param The input element.
+/// @param color The color of the output element.
+/// @param child The input element.
 /// @return The output element colored.
 /// @ingroup dom
 ///
@@ -83,7 +83,7 @@ Decorator color(Color c) {
 }
 
 /// @brief Decorate using a background color.
-/// @param The background color to be applied.
+/// @param color The background color to be applied.
 /// @return The Decorator applying the color.
 /// @ingroup dom
 ///
@@ -92,8 +92,8 @@ Decorator color(Color c) {
 /// ```cpp
 /// Element document = text(L"red") | bgcolor(Color::Red);
 /// ```
-Decorator bgcolor(Color c) {
-  return [c](Element child) { return bgcolor(c, std::move(child)); };
+Decorator bgcolor(Color color) {
+  return [color](Element child) { return bgcolor(color, std::move(child)); };
 }
 
 }  // namespace ftxui

src/ftxui/dom/dbox.cpp

@@ -40,7 +40,7 @@ class DBox : public Node {
 };
 
 /// @brief Stack several element on top of each other.
-/// @param The input element.
+/// @param children The input element.
 /// @return The right aligned element.
 /// @ingroup dom
 Element dbox(Elements children) {

src/ftxui/dom/flex.cpp

@@ -92,6 +92,7 @@ Element filler() {
 
 /// @brief Make a child element to expand proportionnally to the space left in a
 /// container.
+/// @ingroup dom
 ///
 /// #### Examples:
 ///
@@ -114,38 +115,56 @@ Element flex(Element child) {
   return std::make_shared<Flex>(function_flex, std::move(child));
 }
 
+/// @brief Expand/Minimize if possible/needed on the X axis.
+/// @ingroup dom
 Element xflex(Element child) {
   return std::make_shared<Flex>(function_xflex, std::move(child));
 }
 
+/// @brief Expand/Minimize if possible/needed on the Y axis.
+/// @ingroup dom
 Element yflex(Element child) {
   return std::make_shared<Flex>(function_yflex, std::move(child));
 }
 
+/// @brief Expand if possible.
+/// @ingroup dom
 Element flex_grow(Element child) {
   return std::make_shared<Flex>(function_flex_grow, std::move(child));
 }
 
+/// @brief Expand if possible on the X axis.
+/// @ingroup dom
 Element xflex_grow(Element child) {
   return std::make_shared<Flex>(function_xflex_grow, std::move(child));
 }
 
+/// @brief Expand if possible on the Y axis.
+/// @ingroup dom
 Element yflex_grow(Element child) {
   return std::make_shared<Flex>(function_yflex_grow, std::move(child));
 }
 
+/// @brief Minimize if needed.
+/// @ingroup dom
 Element flex_shrink(Element child) {
   return std::make_shared<Flex>(function_flex_shrink, std::move(child));
 }
 
+/// @brief Minimize if needed on the X axis.
+/// @ingroup dom
 Element xflex_shrink(Element child) {
   return std::make_shared<Flex>(function_xflex_shrink, std::move(child));
 }
 
+/// @brief Minimize if needed on the Y axis.
+/// @ingroup dom
 Element yflex_shrink(Element child) {
   return std::make_shared<Flex>(function_yflex_shrink, std::move(child));
 }
 
+/// @brief Make the element not flexible.
+/// @ingroup dom
 Element notflex(Element child) {
   return std::make_shared<Flex>(function_not_flex, std::move(child));
 }

src/ftxui/dom/frame.cpp

@@ -109,7 +109,7 @@ class Frame : public Node {
 /// @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
+/// @see focus
 Element frame(Element child) {
   return std::make_shared<Frame>(unpack(std::move(child)), true, true);
 }

src/ftxui/dom/inverted.cpp

@@ -20,6 +20,9 @@ class Inverted : public NodeDecorator {
   }
 };
 
+/// @brief Add a filter that will invert the foreground and the background
+/// colors.
+/// @ingroup dom
 Element inverted(Element child) {
   return std::make_shared<Inverted>(unpack(std::move(child)));
 }

src/ftxui/dom/node.cpp

@@ -8,24 +8,34 @@ Node::Node() {}
 Node::Node(Elements children) : children(std::move(children)) {}
 Node::~Node() {}
 
+/// @brief Compute how much space an elements needs.
+/// @ingroup dom
 void Node::ComputeRequirement() {
   for (auto& child : children)
     child->ComputeRequirement();
 }
 
+/// @brief Assign a position and a dimension to an element for drawing.
+/// @ingroup dom
 void Node::SetBox(Box box) {
   box_ = box;
 }
 
+/// @brief Display an element on a ftxui::Screen.
+/// @ingroup dom
 void Node::Render(Screen& screen) {
   for (auto& child : children)
     child->Render(screen);
 }
 
+/// @brief Display an element on a ftxui::Screen.
+/// @ingroup dom
 void Render(Screen& screen, const Element& element) {
   Render(screen, element.get());
 }
 
+/// @brief Display an element on a ftxui::Screen.
+/// @ingroup dom
 void Render(Screen& screen, Node* node) {
   // Step 1: Find what dimension this elements wants to be.
   node->ComputeRequirement();

src/ftxui/dom/paragraph.cpp

@@ -4,6 +4,11 @@
 
 namespace ftxui {
 
+/// @brief Return a vector of ftxui::text for every word of the string. This is
+/// useful combined with ftxui::hflow.
+/// @param the_text The string to be splitted.
+/// @ingroup dom
+/// @see hflow.
 Elements paragraph(std::wstring the_text) {
   Elements output;
   std::wstringstream ss(the_text);

src/ftxui/dom/size.cpp

@@ -73,6 +73,12 @@ class Size : public Node {
   int value_;
 };
 
+/// @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.
+/// @ingroup dom
 Decorator size(Direction direction, Constraint constraint, int value) {
   return [=](Element e) {
     return std::make_shared<Size>(std::move(e), direction, constraint, value);

src/ftxui/dom/spinner.cpp

@@ -241,17 +241,23 @@ static const std::vector<std::vector<std::vector<std::wstring>>> elements = {
          L" LOLLOL ",
      }}};
 
-Element spinner(int c, size_t index) {
-  if (c == 0) {
-    index %= 40;
-    if (index > 20)
-      index = 40 - index;
-    return gauge(index * 0.05);
+/// @brief Useful to represent the effect of time and/or events. This display an
+/// ASCII art "video".
+/// @param charset_index The type of "video".
+/// @param image_index The "frame" of the video. You need to increase this for
+///every "step".
+/// @ingroup dom
+Element spinner(int charset_index, size_t image_index) {
+  if (charset_index == 0) {
+    image_index %= 40;
+    if (image_index > 20)
+      image_index = 40 - image_index;
+    return gauge(image_index * 0.05);
   }
-  c %= elements.size();
-  index %= elements[c].size();
+  charset_index %= elements.size();
+  image_index %= elements[charset_index].size();
   std::vector<Element> lines;
-  for (const auto& it : elements[c][index])
+  for (const auto& it : elements[charset_index][image_index])
     lines.push_back(text(it));
   return vbox(std::move(lines));
 }

src/ftxui/dom/text.cpp

@@ -64,10 +64,51 @@ class VText : public Node {
   int width_ = 1;
 };
 
+/// @brief Display a pieve of unicode text.
+/// @ingroup dom
+/// @see ftxui::to_wstring
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = text(L"Hello world!");
+/// ```
+///
+/// ### Output
+///
+/// ```bash
+/// Hello world!
+/// ```
 Element text(std::wstring text) {
   return std::make_shared<Text>(text);
 }
 
+/// @brief Display a pieve of unicode text vertically.
+/// @ingroup dom
+/// @see ftxui::to_wstring
+///
+/// ### Example
+///
+/// ```cpp
+/// Element document = vtext(L"Hello world!");
+/// ```
+///
+/// ### Output
+///
+/// ```bash
+/// H
+/// e
+/// l
+/// l
+/// o
+///
+/// w
+/// o
+/// r
+/// l
+/// d
+/// !
+/// ```
 Element vtext(std::wstring text) {
   return std::make_shared<VText>(text);
 }

src/ftxui/dom/underlined.cpp

@@ -20,6 +20,8 @@ class Underlined : public NodeDecorator {
   }
 };
 
+/// @brief Make the underlined element to be underlined.
+/// @ingroup dom
 Element underlined(Element child) {
   return std::make_shared<Underlined>(unpack(std::move(child)));
 }

src/ftxui/dom/util.cpp

@@ -2,29 +2,57 @@
 
 namespace ftxui {
 
-Element nothing(Element element) {
-  return element;
-}
-
+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
+Element nothing(Element element) {
+  return element;
+}
+
+/// @brief Compose two decorator into one.
+/// @ingroup dom
+///
+/// ### Example
+///
+/// ```cpp
+/// auto decorator = bold | blink;
+/// ```
 Decorator operator|(Decorator a, Decorator b) {
   return compose(a, b);
 }
 
-Elements operator|(Elements es, Decorator d) {
+/// @brief From a set of element, apply a decorator to every elements.
+/// @return the set of decorated element.
+/// @ingroup dom
+Elements operator|(Elements elements, Decorator decorator) {
   Elements output;
-  for (auto& it : es)
-    output.push_back(std::move(it) | d);
+  for (auto& it : elements)
+    output.push_back(std::move(it) | decorator);
   return output;
 }
 
-Element operator|(Element e, Decorator d) {
-  return d(std::move(e));
+/// @brief From an element, apply a decorator.
+/// @return the decorated element.
+/// @ingroup dom
+/// 
+/// ### Example
+///
+/// Both of these are equivalent:
+/// ```cpp
+/// bold(text(L"Hello"));
+/// ```
+/// ```cpp
+/// text(L"Hello") | bold;
+/// ```
+Element operator|(Element element, Decorator decorator) {
+  return decorator(std::move(element));
 }
 
 }  // namespace ftxui

src/ftxui/dom/vbox.cpp

@@ -128,6 +128,7 @@ class VBox : public Node {
 /// @brief A container displaying elements vertically one by one.
 /// @param children The elements in the container
 /// @return The container.
+/// @ingroup dom
 ///
 /// #### Example
 ///