Document the new timetrap interface

OTP-10039

2 files changed, 74 insertions, 35 deletions

diff --git a/lib/common_test/doc/src/common_test_app.xml b/lib/common_test/doc/src/common_test_app.xml
index c7f6c7ce5c..6babdb93af 100644
--- a/lib/common_test/doc/src/common_test_app.xml
+++ b/lib/common_test/doc/src/common_test_app.xml
@@ -187,9 +187,13 @@
 	  test case is allowed to execute (including <c>init_per_testcase/2</c>
 	  and <c>end_per_testcase/2</c>). If the timetrap time is
 	  exceeded, the test case fails with reason
-	  <c>timetrap_timeout</c>. If a <c>TimeFunc</c> function is specified,
-	  it will be called initially and must return a value on
-	  <c>TimeVal</c> format.</p>
+	  <c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to
+	  set a new timetrap by returning a <c>TimeVal</c>. It may also be
+	  used to trigger a timetrap timeout by, at some point, returning a
+	  value other than a <c>TimeVal</c>. (See the
+	  <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
+	  for details).
+	</p>
 	
 	<p>The <c>require</c> tag specifies configuration variables
 	  that are required by test cases (and/or configuration functions)
@@ -313,9 +317,12 @@
 	  test case is allowed to execute (including <c>init_per_testcase/2</c>
 	  and <c>end_per_testcase/2</c>). If the timetrap time is
 	  exceeded, the test case fails with reason
-	  <c>timetrap_timeout</c>. If a <c>TimeFunc</c> function is specified,
-	  it will be called initially and must return a value on
-	  <c>TimeVal</c> format.</p>
+	  <c>timetrap_timeout</c>. A <c>TimeFunc</c> function can be used to
+	  set a new timetrap by returning a <c>TimeVal</c>. It may also be
+	  used to trigger a timetrap timeout by, at some point, returning a
+	  value other than a <c>TimeVal</c>. (See the
+	  <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
+	  for details).</p>
 	
 	<p>The <c>require</c> tag specifies configuration variables
 	  that are required by test cases (and/or configuration functions)
@@ -494,9 +501,12 @@
 	  exceeded, the test case fails with reason
 	  <c>timetrap_timeout</c>. <c>init_per_testcase/2</c>
 	  and <c>end_per_testcase/2</c> are included in the
-	  timetrap time. If a <c>TimeFunc</c> function is specified,
-	  it will be called before the test case (or <c>init_per_testcase/2</c>)
-	  and must return a value on <c>TimeVal</c> format.</p>
+	  timetrap time. A <c>TimeFunc</c> function can be used to
+	  set a new timetrap by returning a <c>TimeVal</c>. It may also be
+	  used to trigger a timetrap timeout by, at some point, returning a
+	  value other than a <c>TimeVal</c>. (See the
+	  <seealso marker="write_test_chapter#timetraps">User's Guide</seealso>
+	  for details).</p>
 	
 	<p>The <c>require</c> tag specifies configuration variables
 	  that are required by the test case (and/or <c>init/end_per_testcase/2</c>).
diff --git a/lib/common_test/doc/src/write_test_chapter.xml b/lib/common_test/doc/src/write_test_chapter.xml
index 09f4f8ed3b..7447bb7673 100644
--- a/lib/common_test/doc/src/write_test_chapter.xml
+++ b/lib/common_test/doc/src/write_test_chapter.xml
@@ -872,34 +872,63 @@
     <marker id="timetraps"></marker>
     <title>Timetrap timeouts</title>
     <p>The default time limit for a test case is 30 minutes, unless a
-      <c>timetrap</c> is specified either by the suite info function
-      or a test case info function. The timetrap timeout value defined
-      in <c>suite/0</c> is the value that will be used for each test case
-      in the suite (as well as for the configuration functions
-      <c>init_per_suite/1</c> and <c>end_per_suite</c>). A timetrap timeout
-      value set with the test case info function will override the value set
-      by <c>suite/0</c>, but only for that particular test case.</p>
-    <p>It is also possible to set/reset a timetrap during test case (or
-      configuration function) execution. This is done by calling
-      <c>ct:timetrap/1</c>. This function will cancel the current timetrap
-      and start a new one.</p>
+    <c>timetrap</c> is specified either by the suite-, group-,
+    or test case info function. The timetrap timeout value defined by
+    <c>suite/0</c> is the value that will be used for each test case
+    in the suite (as well as for the configuration functions
+    <c>init_per_suite/1</c>, <c>end_per_suite/1</c>, <c>init_per_group/2</c>,
+    and <c>end_per_group/2</c>). A timetrap value defined by
+    <c>group(GroupName)</c> overrides one defined by <c>suite()</c>
+    and will be used for each test case in group <c>GroupName</c>, and any
+    of its sub-groups. If a timetrap value is defined by <c>group/1</c>
+    for a sub-group, it overrides that of its higher level groups. Timetrap
+    values set by individual test cases (by means of the test case info
+    function) overrides both group- and suite- level timetraps.</p>
+    
+    <p>It is also possible to dynamically set/reset a timetrap during the
+    excution of a test case, or configuration function. This is done by calling
+    <c>ct:timetrap/1</c>. This function cancels the current timetrap
+    and starts a new one (that stays active until timeout, or end of the
+    current function).</p>
+    
     <p>Timetrap values can be extended with a multiplier value specified at
-      startup with the <c>multiply_timetraps</c> option. It is also possible
-      to let Test Server decide to scale up timetrap timeout values
-      automatically, e.g. if tools such as cover or trace are running during
-      the test. This feature is disabled by default and can be enabled with
-      the <c>scale_timetraps</c> start option.</p>
+    startup with the <c>multiply_timetraps</c> option. It is also possible
+    to let the test server decide to scale up timetrap timeout values
+    automatically, e.g. if tools such as cover or trace are running during
+    the test. This feature is disabled by default and can be enabled with
+    the <c>scale_timetraps</c> start option.</p>
+    
     <p>If a test case needs to suspend itself for a time that also gets
-      multipled by <c>multiply_timetraps</c>, and possibly scaled up if
-      <c>scale_timetraps</c> is enabled, the function <c>ct:sleep/1</c>
-      may be called.</p>
-    <p>A function (<c>fun</c> or <c>MFA</c>) may be specified as timetrap value
-      in the suite- and test case info function, e.g:</p>
-      <p><c>{timetrap,{test_utils,get_timetrap_value,[?MODULE,system_start]}}</c></p>
-      <p>The function will be called initially by Common Test (before execution
-	of the suite or the test case) and must return a time value such as an
-	integer (millisec), or a <c>{SecMinOrHourTag,Time}</c> tuple. More
-	information can be found in the <c>common_test</c> reference manual.</p>
+    multipled by <c>multiply_timetraps</c> (and possibly also scaled up if
+    <c>scale_timetraps</c> is enabled), the function <c>ct:sleep/1</c>
+    may be used (instead of e.g. <c>timer:sleep/1</c>).</p>
+    
+    <p>A function (<c>fun/0</c> or <c>MFA</c>) may be specified as
+    timetrap value in the suite-, group- and test case info function, as
+    well as argument to the <c>ct:timetrap/1</c> function. Examples:</p>
+
+    <p><c>{timetrap,{my_test_utils,timetrap,[?MODULE,system_start]}}</c></p>
+    <p><c>ct:timetrap(fun() -> my_timetrap(TestCaseName, Config) end)</c></p>
+
+    <p>The user timetrap function may be used for two things:</p>
+    <list>
+      <item>To act as a timetrap - the timeout is triggered when the
+      function returns.</item>
+      <item>To return a timetrap time value (other than a function).</item>
+    </list>
+    <p>Before execution of the timetrap function (which is performed
+    on a parallel, dedicated timetrap process), Common Test cancels
+    any previously set timer for the test case or configuration function.    
+    When the timetrap function returns, the timeout is triggered, <em>unless</em>
+    the return value is a valid timetrap time, such as an integer,
+    or a <c>{SecMinOrHourTag,Time}</c> tuple (see the
+    <seealso marker="common_test">common_test reference manual</seealso> for
+    details). If a time value is returned, a new timetrap is started
+    to generate a timeout after the specified time.</p>
+
+    <p>The user timetrap function may of course return a time value after a delay,
+    and if so, the effective timetrap time is the delay time <em>plus</em> the
+    returned time.</p>
   </section>
 
   <section>