From: YuriyRyabikov <22548029+kurok@users.noreply.github.com>
Date: Tue, 31 Mar 2026 09:30:32 +0000 (+0100)
Subject: libsmartcols: document scols_table_calculate() constraints
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=883cf25dc599dac737f09b62280837ab68e83e31;p=thirdparty%2Futil-linux.git

libsmartcols: document scols_table_calculate() constraints

Clarify that the table must not be modified after calculate, and
that the calculation is consumed by the next scols_print_table()
call only.
---

diff --git a/libsmartcols/src/print-api.c b/libsmartcols/src/print-api.c
index 7751d327d..4aa5b91aa 100644
--- a/libsmartcols/src/print-api.c
+++ b/libsmartcols/src/print-api.c
@@ -108,8 +108,13 @@ int scols_table_print_range_to_string(
  * set up a pager with "less --header" to freeze the header row and
  * first column.
  *
- * Note that scols_print_table() will skip recalculation if this
- * function has already been called.
+ * After this call, the table must not be modified (no new columns,
+ * no new data in existing columns, etc.) because the calculated state
+ * remains set until the table is printed.
+ *
+ * The calculation is valid only for the next scols_print_table() call
+ * (not scols_table_print_range()), and will be recalculated for every
+ * subsequent printing.
  *
  * Returns: 0, a negative value in case of an error.
  *