diff --git a/lib/test.gi b/lib/test.gi
index d02100f2c7..47f164dd03 100644
--- a/lib/test.gi
+++ b/lib/test.gi
@@ -292,6 +292,8 @@ end);
 ##  lines, compares the actual output with the output stored in 
 ##  <Arg>fname</Arg> and reports differences. With an optional record as
 ##  argument <Arg>optrec</Arg> details of this process can be adjusted.
+##  Note that the <C>rewriteToFile</C> option is especially useful for
+##  generating test files.
 ##  <P/>
 ##  More precisely, the content of <Arg>fname</Arg> must have the following
 ##  format. <Br/>
@@ -371,7 +373,11 @@ end);
 ##  and that file is written with the same input and comment lines as
 ##  <Arg>fname</Arg> but the output substituted by the newly generated
 ##  version; if it is bound to <K>true</K>, then this is treated as if
-##  it was bound to <Arg>fname</Arg> (default is <K>false</K>).</Item>
+##  it was bound to <Arg>fname</Arg> (default is <K>false</K>). This is
+##  especially useful for generating test files because it ensures that
+##  the test files are formatted exactly as <Ref Func="Test" /> expects
+##  them to be.
+##  </Item>
 ##  <Mark><C>writeTimings</C></Mark>
 ##  <Item>If this is bound to a string it is considered as a file name,
 ##  that file is written and contains timing information for each input 
@@ -705,6 +711,8 @@ end);
 ##  printed, and <K>true</K> returned if all tests passed.
 ##  <P/>
 ##  If the optional argument <Arg>optrec</Arg> is given it must be a record.
+##  Note that the <C>rewriteToFile</C> option is especially useful for
+##  generating test files.
 ##  The following components of <Arg>optrec</Arg> are recognized and can change
 ##  the default behaviour of <Ref Func="TestDirectory" />:
 ##  <List>
@@ -725,6 +733,9 @@ end);
 ##  <Mark><C>rewriteToFile</C></Mark>
 ##  <Item>If <K>true</K>, then rewrite each test file to disc, with the output substituted
 ##  by the results of running the test (defaults to <K>false</K>).
+##  This is especially useful for generating test files because it ensures that
+##  the test files are formatted exactly as <Ref Func="Test" /> expects
+##  them to be.
 ##  </Item>
 ##  <Mark><C>exclude</C></Mark>
 ##  <Item>A list of file and directory names which will be excluded from
diff --git a/tst/testspecial/broken-test.g.out b/tst/testspecial/broken-test.g.out
index dfae57c88d..9bfc19f544 100644
--- a/tst/testspecial/broken-test.g.out
+++ b/tst/testspecial/broken-test.g.out
@@ -1,7 +1,7 @@
 gap> Test("broken-test-2.tst", rec(width := 800));
 Error, Invalid test file: #@ command found in the middle of a single test at broken-test-2.tst:5 at GAPROOT/lib/test.gi:31 called from
 testError( "Invalid test file: #@ command found in the middle of a single test" ); at GAPROOT/lib/test.gi:129 called from
-ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:563 called from
+ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:569 called from
 <function "Test">( <arguments> )
  called from read-eval loop at *stdin*:2
 type 'quit;' to quit to outer loop
@@ -9,7 +9,7 @@ brk> quit;
 gap> Test("broken-test-3.tst", rec(width := 800));
 Error, Invalid test file at broken-test-3.tst:5 at GAPROOT/lib/test.gi:31 called from
 testError( "Invalid test file" ); at GAPROOT/lib/test.gi:135 called from
-ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:563 called from
+ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:569 called from
 <function "Test">( <arguments> )
  called from read-eval loop at *stdin*:2
 type 'quit;' to quit to outer loop
@@ -17,7 +17,7 @@ brk> quit;
 gap> Test("broken-test-4.tst", rec(width := 800));
 Error, Invalid test file: Nested #@if at broken-test-4.tst:2 at GAPROOT/lib/test.gi:31 called from
 testError( "Invalid test file: Nested #@if" ); at GAPROOT/lib/test.gi:52 called from
-ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:563 called from
+ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:569 called from
 <function "Test">( <arguments> )
  called from read-eval loop at *stdin*:2
 type 'quit;' to quit to outer loop
@@ -25,7 +25,7 @@ brk> quit;
 gap> Test("broken-test-5.tst", rec(width := 800));
 Error, Invalid test file: two #@else at broken-test-5.tst:7 at GAPROOT/lib/test.gi:31 called from
 testError( "Invalid test file: two #@else" ); at GAPROOT/lib/test.gi:63 called from
-ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:563 called from
+ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:569 called from
 <function "Test">( <arguments> )
  called from read-eval loop at *stdin*:2
 type 'quit;' to quit to outer loop
@@ -33,7 +33,7 @@ brk> quit;
 gap> Test("invalidtestfile.tst", rec(width := 800));
 Error, Invalid test file at invalidtestfile.tst:7 at GAPROOT/lib/test.gi:31 called from
 testError( "Invalid test file" ); at GAPROOT/lib/test.gi:135 called from
-ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:563 called from
+ParseTestInput( full, opts.ignoreComments, fnam ) at GAPROOT/lib/test.gi:569 called from
 <function "Test">( <arguments> )
  called from read-eval loop at *stdin*:2
 type 'quit;' to quit to outer loop