File 0164-Add-documentation-about-ct-comment-to-documentation.patch of Package erlang
From 3b0c7d2af56950f11ab65fa03f84ea848ff50cfb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20W=C4=85sowski?= <michal@erlang.org>
Date: Fri, 9 Jan 2026 11:15:29 +0100
Subject: [PATCH] Add documentation about ct:comment to documentation
---
.../doc/guides/ct_hooks_chapter.md | 20 ++++++++++++
lib/common_test/internal_doc/ct_notes.md | 31 +++++++++++++++++++
lib/common_test/src/ct.erl | 12 +++++++
3 files changed, 63 insertions(+)
diff --git a/lib/common_test/doc/guides/ct_hooks_chapter.md b/lib/common_test/doc/guides/ct_hooks_chapter.md
index f68b71d942..ccbb058d5b 100644
--- a/lib/common_test/doc/guides/ct_hooks_chapter.md
+++ b/lib/common_test/doc/guides/ct_hooks_chapter.md
@@ -281,6 +281,26 @@ After any post hook has been executed for all installed CTHs,
skipped, respectively. You cannot affect the outcome of the tests any further at
this point.
+[](){: #comment }
+
+### Comment in hooks
+
+Be aware that there are limitations on processes from which `ct:comment/1-2` can be called.
+They are explained in `ct:comment/1`.
+
+In addition to that the behavior of `ct:comment/1-2` when called from hook functions
+[init/2](`c:ct_hooks:init/2`) and [terminate/1](`c:ct_hooks:terminate/1`) depends on the hook's
+[scope](#scope).
+
+If hook is installed in a way that scope begins before
+[pre_init_per_suite/3](`c:ct_hooks:pre_init_per_suite/3`) is called, then calling `ct:comment/1-2`
+from a process running either `init/2` or `terminate/1` does not result in the comment being printed anywhere.
+
+Otherwise the comment is printed in the same place a process running the
+[`init_per_suite`](`c:ct_suite:init_per_suite/1`) or [`end_per_suite`](`c:ct_suite:end_per_suite/1`)
+functions would print it
+(respectively init_per_suite and end_per_suite rows in generated Common Test HTML logs).
+
[](){: #synchronizing }
## Synchronizing External User Applications with Common Test
diff --git a/lib/common_test/internal_doc/ct_notes.md b/lib/common_test/internal_doc/ct_notes.md
index fd9337e47c..ebfecdaafb 100644
--- a/lib/common_test/internal_doc/ct_notes.md
+++ b/lib/common_test/internal_doc/ct_notes.md
@@ -251,3 +251,34 @@ mindmap
questions
why call_end_conf not called when init/end_per_testcase not defined?
```
+
+
+
+## Comment in hooks
+
+This table presents information about where `ct:comment/1-2` prints to, depending on how the hook was installed:
+
+| Hook function | Install in: `ct_run`, `ct:run_test/1`, Test Specification | Install in: suite/0, init_per_suite/1, init_per_group/2 |
+| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------- |
+| id/1 | init_per_suite row | init_per_suite row |
+| init/2 | nowhere | init_per_suite row |
+| post_all/3 | nowhere | nowhere |
+| post_groups/4 | nowhere | nowhere |
+| pre_init_per_suite/3 | init_per_suite row | init_per_suite row |
+| post_init_per_suite/4 | init_per_suite row | init_per_suite row |
+| pre_init_per_group/3,4 | init_per_group row | init_per_group row |
+| post_init_per_group/4,5 | init_per_group row | init_per_group row |
+| pre_init_per_testcase/3,4 | testcase row | testcase row |
+| post_init_per_testcase/4,5 | testcase row | testcase row |
+| post_init_per_testcase/4,5 | testcase row | testcase row |
+| pre_end_per_testcase/3,4 | testcase row | testcase row |
+| post_end_per_testcase/4,5 | testcase row | testcase row |
+| pre_end_per_group/3,4 | end_per_group row | end_per_group row |
+| post_end_per_group/4,5 | end_per_group row | end_per_group row |
+| pre_end_per_suite/3 | end_per_suite row | end_per_suite row |
+| post_end_per_suite/4 | end_per_suite row | end_per_suite row |
+| on_tc_skip/4 | testcase row | testcase row |
+| on_tc_fail/4 | nowhere | nowhere |
+| terminate/1 | nowhere | end_per_suite row |
+
+_Table: Behavior of `ct:comment/1-2` depending on hook installation method_
diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl
index 82dec1697d..74fde12338 100644
--- a/lib/common_test/src/ct.erl
+++ b/lib/common_test/src/ct.erl
@@ -1055,6 +1055,18 @@ suite result page.
If called several times, only the last comment is printed. The test case return
value `{comment,Comment}` overwrites the string set by this function.
+
+> #### Warning {: .warning }
+>
+> This function (and `ct:comment/2`) should only be called from the process running
+> the common_test functions, typically the test case process or its descendant.
+> Be aware that if you spawn a new process in one common_test function (e.g. `init_per_suite`)
+> and then execute `ct:comment/1-2` in that new process while the test execution has moved
+> to another common_test function (e.g. `init_per_testcase` or test case function) the comment
+> might not be printed in the correct place in HTML logs or at all.
+>
+> Calling this function from a process that is neither a common_test process, nor its
+> descendant does not result in the comment being printed anywhere.
""".
-spec comment(Comment) -> ok
when Comment :: term().
--
2.51.0
