Improve documentation (#1058)

* Remove @ingroup from class member definitions * Add the documentation for every public classes.
2025-11-15 11:38:56 +08:00 · 2025-06-05 11:35:14 +02:00
parent a86d8f32d7
commit 14da21b0ee
30 changed files with 177 additions and 143 deletions
--- a/src/ftxui/dom/flexbox_config.cpp
+++ b/src/ftxui/dom/flexbox_config.cpp
@@ -6,42 +6,36 @@
 namespace ftxui {

 /// @brief Set the flexbox direction.
-/// @ingroup dom
 FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::Direction d) {
  this->direction = d;
  return *this;
 }

 /// @brief Set the flexbox wrap.
-/// @ingroup dom
 FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::Wrap w) {
  this->wrap = w;
  return *this;
 }

 /// @brief Set the flexbox justify content.
-/// @ingroup dom
 FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::JustifyContent j) {
  this->justify_content = j;
  return *this;
 }

 /// @brief Set the flexbox align items.
-/// @ingroup dom
 FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::AlignItems a) {
  this->align_items = a;
  return *this;
 }

 /// @brief Set the flexbox align content.
-/// @ingroup dom
 FlexboxConfig& FlexboxConfig::Set(FlexboxConfig::AlignContent a) {
  this->align_content = a;
  return *this;
 }

 /// @brief Set the flexbox flex direction.
-/// @ingroup dom
 FlexboxConfig& FlexboxConfig::SetGap(int x, int y) {
  this->gap_x = x;
  this->gap_y = y;
--- a/src/ftxui/dom/linear_gradient.cpp
+++ b/src/ftxui/dom/linear_gradient.cpp
@@ -189,13 +189,11 @@ class LinearGradientColor : public NodeDecorator {
 ///    .Stop(Color::Green, 0.5)
 ///    .Stop(Color::Blue, 1.0);;
 /// ```
-/// @ingroup dom
 LinearGradient::LinearGradient() = default;

 /// @brief Build a gradient with two colors.
 /// @param begin The color at the beginning of the gradient.
 /// @param end The color at the end of the gradient.
-/// @ingroup dom
 LinearGradient::LinearGradient(Color begin, Color end)
    : LinearGradient(0, begin, end) {}

@@ -203,7 +201,6 @@ LinearGradient::LinearGradient(Color begin, Color end)
 /// @param a The angle of the gradient.
 /// @param begin The color at the beginning of the gradient.
 /// @param end The color at the end of the gradient.
-/// @ingroup dom
 LinearGradient::LinearGradient(float a, Color begin, Color end) : angle(a) {
  stops.push_back({begin, {}});
  stops.push_back({end, {}});
@@ -212,7 +209,6 @@ LinearGradient::LinearGradient(float a, Color begin, Color end) : angle(a) {
 /// @brief Set the angle of the gradient.
 /// @param a The angle of the gradient.
 /// @return The gradient.
-/// @ingroup dom
 LinearGradient& LinearGradient::Angle(float a) {
  angle = a;
  return *this;
@@ -221,7 +217,6 @@ LinearGradient& LinearGradient::Angle(float a) {
 /// @brief Add a color stop to the gradient.
 /// @param c The color of the stop.
 /// @param p The position of the stop.
-/// @return The gradient.
 LinearGradient& LinearGradient::Stop(Color c, float p) {
  stops.push_back({c, p});
  return *this;
@@ -230,7 +225,6 @@ LinearGradient& LinearGradient::Stop(Color c, float p) {
 /// @brief Add a color stop to the gradient.
 /// @param c The color of the stop.
 /// @return The gradient.
-/// @ingroup dom
 /// @note The position of the stop is interpolated from nearby stops.
 LinearGradient& LinearGradient::Stop(Color c) {
  stops.push_back({c, {}});
--- a/src/ftxui/dom/node.cpp
+++ b/src/ftxui/dom/node.cpp
@@ -17,7 +17,6 @@ Node::Node(Elements children) : children_(std::move(children)) {}
 Node::~Node() = default;

 /// @brief Compute how much space an element needs.
-/// @ingroup dom
 void Node::ComputeRequirement() {
  if (children_.empty()) {
    return;
@@ -39,13 +38,11 @@ void Node::ComputeRequirement() {
 }

 /// @brief Assign a position and a dimension to an element for drawing.
-/// @ingroup dom
 void Node::SetBox(Box box) {
  box_ = box;
 }

 /// @brief Compute the selection of an element.
-/// @ingroup dom
 void Node::Select(Selection& selection) {
  // If this Node box_ doesn't intersect with the selection, then no selection.
  if (Box::Intersection(selection.GetBox(), box_).IsEmpty()) {
@@ -59,7 +56,6 @@ void Node::Select(Selection& selection) {
 }

 /// @brief Display an element on a ftxui::Screen.
-/// @ingroup dom
 void Node::Render(Screen& screen) {
  for (auto& child : children_) {
    child->Render(screen);
--- a/src/ftxui/dom/table.cpp
+++ b/src/ftxui/dom/table.cpp
@@ -44,14 +44,12 @@ void Order(int& a, int& b) {
 }  // namespace

 /// @brief Create an empty table.
-/// @ingroup dom
 Table::Table() {
  Initialize({});
 }

 /// @brief Create a table from a vector of vector of string.
 /// @param input The input data.
-/// @ingroup dom
 Table::Table(std::vector<std::vector<std::string>> input) {
  std::vector<std::vector<Element>> output;
  output.reserve(input.size());
@@ -68,14 +66,12 @@ Table::Table(std::vector<std::vector<std::string>> input) {

 /// @brief Create a table from a vector of vector of Element
 /// @param input The input elements.
-/// @ingroup dom
 Table::Table(std::vector<std::vector<Element>> input) {
  Initialize(std::move(input));
 }

 // @brief Create a table from a list of list of string.
 // @param init The input data.
-// @ingroup dom
 Table::Table(std::initializer_list<std::vector<std::string>> init) {
  std::vector<std::vector<Element>> input;
  for (const auto& row : init) {
@@ -139,7 +135,6 @@ void Table::Initialize(std::vector<std::vector<Element>> input) {
 /// @brief Select a row of the table.
 /// @param index The index of the row to select.
 /// @note You can use negative index to select from the end.
-/// @ingroup dom
 TableSelection Table::SelectRow(int index) {
  return SelectRectangle(0, -1, index, index);
 }
@@ -148,7 +143,6 @@ TableSelection Table::SelectRow(int index) {
 /// @param row_min The first row to select.
 /// @param row_max The last row to select.
 /// @note You can use negative index to select from the end.
-/// @ingroup dom
 TableSelection Table::SelectRows(int row_min, int row_max) {
  return SelectRectangle(0, -1, row_min, row_max);
 }
@@ -156,7 +150,6 @@ TableSelection Table::SelectRows(int row_min, int row_max) {
 /// @brief Select a column of the table.
 /// @param index The index of the column to select.
 /// @note You can use negative index to select from the end.
-/// @ingroup dom
 TableSelection Table::SelectColumn(int index) {
  return SelectRectangle(index, index, 0, -1);
 }
@@ -165,7 +158,6 @@ TableSelection Table::SelectColumn(int index) {
 /// @param column_min The first column to select.
 /// @param column_max The last column to select.
 /// @note You can use negative index to select from the end.
-/// @ingroup dom
 TableSelection Table::SelectColumns(int column_min, int column_max) {
  return SelectRectangle(column_min, column_max, 0, -1);
 }
@@ -174,7 +166,6 @@ TableSelection Table::SelectColumns(int column_min, int column_max) {
 /// @param column The column of the cell to select.
 /// @param row The row of the cell to select.
 /// @note You can use negative index to select from the end.
-/// @ingroup dom
 TableSelection Table::SelectCell(int column, int row) {
  return SelectRectangle(column, column, row, row);
 }
@@ -185,7 +176,6 @@ TableSelection Table::SelectCell(int column, int row) {
 /// @param row_min The first row to select.
 /// @param row_max The last row to select.
 /// @note You can use negative index to select from the end.
-/// @ingroup dom
 TableSelection Table::SelectRectangle(int column_min,
                                      int column_max,
                                      int row_min,
@@ -207,7 +197,6 @@ TableSelection Table::SelectRectangle(int column_min,
 }

 /// @brief Select all the table.
-/// @ingroup dom
 TableSelection Table::SelectAll() {
  TableSelection output;  // NOLINT
  output.table_ = this;
@@ -220,7 +209,6 @@ TableSelection Table::SelectAll() {

 /// @brief Render the table.
 /// @return The rendered table. This is an element you can draw.
-/// @ingroup dom
 Element Table::Render() {
  for (int y = 0; y < dim_y_; ++y) {
    for (int x = 0; x < dim_x_; ++x) {
@@ -250,7 +238,6 @@ Element Table::Render() {
 /// @brief Apply the `decorator` to the selection.
 /// This decorate both the cells, the lines and the corners.
 /// @param decorator The decorator to apply.
-/// @ingroup dom
 // NOLINTNEXTLINE
 void TableSelection::Decorate(Decorator decorator) {
  for (int y = y_min_; y <= y_max_; ++y) {
@@ -264,7 +251,6 @@ void TableSelection::Decorate(Decorator decorator) {
 /// @brief Apply the `decorator` to the selection.
 /// @param decorator The decorator to apply.
 /// This decorate only the cells.
-/// @ingroup dom
 // NOLINTNEXTLINE
 void TableSelection::DecorateCells(Decorator decorator) {
  for (int y = y_min_; y <= y_max_; ++y) {
@@ -282,7 +268,6 @@ void TableSelection::DecorateCells(Decorator decorator) {
 /// @param decorator The decorator to apply.
 /// @param modulo The modulo of the lines to decorate.
 /// @param shift The shift of the lines to decorate.
-/// @ingroup dom
 // NOLINTNEXTLINE
 void TableSelection::DecorateAlternateColumn(Decorator decorator,
                                             int modulo,
@@ -302,7 +287,6 @@ void TableSelection::DecorateAlternateColumn(Decorator decorator,
 /// @param decorator The decorator to apply.
 /// @param modulo The modulo of the lines to decorate.
 /// @param shift The shift of the lines to decorate.
-/// @ingroup dom
 // NOLINTNEXTLINE
 void TableSelection::DecorateAlternateRow(Decorator decorator,
                                          int modulo,
@@ -322,7 +306,6 @@ void TableSelection::DecorateAlternateRow(Decorator decorator,
 /// @param decorator The decorator to apply.
 /// @param modulo The modulo of the corners to decorate.
 /// @param shift The shift of the corners to decorate.
-/// @ingroup dom
 // NOLINTNEXTLINE
 void TableSelection::DecorateCellsAlternateColumn(Decorator decorator,
                                                  int modulo,
@@ -342,7 +325,6 @@ void TableSelection::DecorateCellsAlternateColumn(Decorator decorator,
 /// @param decorator The decorator to apply.
 /// @param modulo The modulo of the corners to decorate.
 /// @param shift The shift of the corners to decorate.
-/// @ingroup dom
 // NOLINTNEXTLINE
 void TableSelection::DecorateCellsAlternateRow(Decorator decorator,
                                               int modulo,
@@ -359,7 +341,6 @@ void TableSelection::DecorateCellsAlternateRow(Decorator decorator,

 /// @brief Apply a `border` around the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::Border(BorderStyle border) {
  BorderLeft(border);
  BorderRight(border);
@@ -378,7 +359,6 @@ void TableSelection::Border(BorderStyle border) {

 /// @brief Draw some separator lines in the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::Separator(BorderStyle border) {
  for (int y = y_min_ + 1; y <= y_max_ - 1; ++y) {
    for (int x = x_min_ + 1; x <= x_max_ - 1; ++x) {
@@ -394,7 +374,6 @@ void TableSelection::Separator(BorderStyle border) {

 /// @brief Draw some vertical separator lines in the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::SeparatorVertical(BorderStyle border) {
  for (int y = y_min_ + 1; y <= y_max_ - 1; ++y) {
    for (int x = x_min_ + 1; x <= x_max_ - 1; ++x) {
@@ -408,7 +387,6 @@ void TableSelection::SeparatorVertical(BorderStyle border) {

 /// @brief Draw some horizontal separator lines in the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::SeparatorHorizontal(BorderStyle border) {
  for (int y = y_min_ + 1; y <= y_max_ - 1; ++y) {
    for (int x = x_min_ + 1; x <= x_max_ - 1; ++x) {
@@ -422,7 +400,6 @@ void TableSelection::SeparatorHorizontal(BorderStyle border) {

 /// @brief Draw some separator lines to the left side of the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::BorderLeft(BorderStyle border) {
  for (int y = y_min_; y <= y_max_; y++) {
    table_->elements_[y][x_min_] =
@@ -432,7 +409,6 @@ void TableSelection::BorderLeft(BorderStyle border) {

 /// @brief Draw some separator lines to the right side of the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::BorderRight(BorderStyle border) {
  for (int y = y_min_; y <= y_max_; y++) {
    table_->elements_[y][x_max_] =
@@ -442,7 +418,6 @@ void TableSelection::BorderRight(BorderStyle border) {

 /// @brief Draw some separator lines to the top side of the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::BorderTop(BorderStyle border) {
  for (int x = x_min_; x <= x_max_; x++) {
    table_->elements_[y_min_][x] =
@@ -452,7 +427,6 @@ void TableSelection::BorderTop(BorderStyle border) {

 /// @brief Draw some separator lines to the bottom side of the selection.
 /// @param border The border style to apply.
-/// @ingroup dom
 void TableSelection::BorderBottom(BorderStyle border) {
  for (int x = x_min_; x <= x_max_; x++) {
    table_->elements_[y_max_][x] =