Improve documentation (#1058)

* Remove @ingroup from class member definitions
* Add the documentation for every public classes.

include/ftxui/dom/canvas.hpp

@@ -20,6 +20,21 @@
 
 namespace ftxui {
 
+/// @brief Canvas is a drawable buffer associated with drawing operations.
+///
+/// Canvas is a drawable area that can be used to create complex graphics. It
+/// supports drawing points, lines, circles, ellipses, text, and images using
+/// braille, block, or normal characters.
+///
+/// Note: A terminal contains cells. A cells is a unit of:
+/// - 2x4 braille characters (1x1 pixel)
+/// - 2x2 block characters (2x2 pixels)
+/// - 2x4 normal characters (2x4 pixels)
+/// 
+/// You need to multiply the x coordinate by 2 and the y coordinate by 4 to
+/// get the correct position in the terminal.
+///
+/// @ingroup dom
 struct Canvas {
  public:
   Canvas() = default;

include/ftxui/dom/direction.hpp

@@ -5,6 +5,11 @@
 #define FTXUI_DOM_DIRECTION_HPP
 
 namespace ftxui {
+
+/// @brief Direction is an enumeration that represents the four cardinal
+/// directions.
+///
+/// @ingroup dom
 enum class Direction {
   Up = 0,
   Down = 1,

include/ftxui/dom/elements.hpp

@@ -24,6 +24,14 @@ using Elements = std::vector<Element>;
 using Decorator = std::function<Element(Element)>;
 using GraphFunction = std::function<std::vector<int>(int, int)>;
 
+/// @brief BorderStyle is an enumeration that represents the different styles
+/// of borders that can be applied to elements in the terminal UI.
+///
+/// BorderStyle is an enumeration that represents the different styles of
+/// borders that can be applied to elements in the terminal UI.
+/// It is used to define the visual appearance of borders around elements,
+/// such as windows, frames, or separators.
+/// @ingroup dom
 enum BorderStyle {
   LIGHT,
   DASHED,

include/ftxui/dom/flexbox_config.hpp

@@ -12,6 +12,19 @@
 
 namespace ftxui {
 
+
+/// @brief FlexboxConfig is a configuration structure that defines the layout
+/// properties for a flexbox container.
+//
+/// It allows you to specify the direction of the flex items, whether they
+/// should wrap, how they should be justified along the main axis, and how
+/// they should be aligned along the cross axis.
+/// It also includes properties for gaps between flex items in both the
+/// main and cross axes.
+/// This structure is used to configure the layout behavior of flexbox
+/// containers in a terminal user interface.
+///
+/// @ingroup dom
 struct FlexboxConfig {
   /// This establishes the main-axis, thus defining the direction flex items are
   /// placed in the flex container. Flexbox is (aside wrapping) single-direction

include/ftxui/dom/linear_gradient.hpp

@@ -27,8 +27,15 @@ namespace ftxui {
 /// LinearGradient(Color::Red, Color::Blue);
 /// LinearGradient(45, Color::Red, Color::Blue);
 /// ```
+///
+/// @ingroup dom
 struct LinearGradient {
   float angle = 0.f;
+
+  /// A stop is a color at a specific position in the gradient.
+  /// The position is a value between 0.0 and 1.0,
+  /// where 0.0 is the start of the gradient
+  /// and 1.0 is the end of the gradient.
   struct Stop {
     Color color = Color::Default;
     std::optional<float> position;

include/ftxui/dom/node.hpp

@@ -20,6 +20,20 @@ class Screen;
 using Element = std::shared_ptr<Node>;
 using Elements = std::vector<Element>;
 
+/// @brief Node is the base class for all elements in the DOM tree.
+///
+/// It represents a single node in the document object model (DOM) and provides
+/// the basic structure for layout and rendering.
+/// It contains methods for computing layout requirements, setting the box
+/// dimensions, selecting content, rendering to the screen, and checking the
+/// layout status.
+/// It typically contains child elements, which are also instances of Node.
+///
+/// Users are expected to derive from this class to create custom elements.
+///
+/// A list of builtin elements can be found in the `elements.hpp` file.
+///
+/// @ingroup dom
 class Node {
  public:
   Node();

include/ftxui/dom/requirement.hpp

@@ -10,6 +10,11 @@
 namespace ftxui {
 class Node;
 
+/// @brief Requirement is a structure that defines the layout requirements for a
+/// Node in the terminal user interface.
+///
+/// It specifies the minimum size required to fully draw the element,
+/// @ingroup dom
 struct Requirement {
   // The required size to fully draw the element.
   int min_x = 0;

include/ftxui/dom/selection.hpp

@@ -13,7 +13,12 @@
 
 namespace ftxui {
 
-/// @brief Represent a selection in the terminal.
+/// @brief Represents a selection in a terminal user interface.
+///
+/// Selection is a class that represents the two endpoints of a selection in a
+/// terminal user interface.
+///
+/// @ingroup dom
 class Selection {
  public:
   Selection();  // Empty selection.

include/ftxui/dom/table.hpp

@@ -11,28 +11,28 @@
 
 namespace ftxui {
 
-// Usage:
-//
-// Initialization:
-// ---------------
-//
-// auto table = Table({
-//   {"X", "Y"},
-//   {"-1", "1"},
-//   {"+0", "0"},
-//   {"+1", "1"},
-// });
-//
-// table.SelectAll().Border(LIGHT);
-//
-// table.SelectRow(1).Border(DOUBLE);
-// table.SelectRow(1).SeparatorInternal(Light);
-//
-// std::move(table).Element();
-
 class Table;
 class TableSelection;
 
+/// @brief Table is a utility to draw tables.
+///
+/// **example**
+/// ```cpp
+/// auto table = Table({
+///  {"X", "Y"},
+///  {"-1", "1"},
+///  {"+0", "0"},
+///  {"+1", "1"},
+/// });
+///
+/// table.SelectAll().Border(LIGHT);
+/// table.SelectRow(1).Border(DOUBLE);
+/// table.SelectRow(1).SeparatorInternal(LIGHT);
+///
+/// std::move(table).Render();
+/// ```
+///
+/// @ingroup dom
 class Table {
  public:
   Table();