tests: 061_undo_tree_spec: minor edits

test/functional/legacy/061_undo_tree_spec.lua

@@ -6,8 +6,8 @@ local feed, insert, source, eq, eval, clear, execute, expect, wait =
   helpers.clear, helpers.execute, helpers.expect, helpers.wait
 
 local function expect_empty_buffer()
-  -- The space will be removed by helpers.dedent but is needed as dedent will
-  -- throw an error if it can not find the common indent of the given lines.
+  -- The space will be removed by helpers.dedent but is needed because dedent
+  -- will fail if it can not find the common indent of the given lines.
   return expect(' ')
 end
 local function expect_line(line)
@@ -20,7 +20,7 @@ local function write_file(name, text)
   file:close()
 end
 
-describe('undo:', function()
+describe('undo tree:', function()
   before_each(clear)
   teardown(function()
     os.remove('Xtest.source')
@@ -34,17 +34,16 @@ describe('undo:', function()
       os.remove('Xtest')
     end)
 
-    it('work with time specifications and g- and g+', function()
+    it('time specifications, g- g+', function()
       -- We write the test text to a file in order to prevent nvim to record
       -- the inserting of the text into the undo history.
       write_file('Xtest', '\n123456789\n')
 
-
       -- `:earlier` and `:later` are (obviously) time-sensitive, so this test
       -- sometimes fails if the system is under load. It is wrapped in a local 
       -- function to allow multiple attempts.
       local function test_earlier_later()
-	clear()
+        clear()
         execute('e Xtest')
         -- Assert that no undo history is present.
         eq({}, eval('undotree().entries'))
@@ -100,6 +99,9 @@ describe('undo:', function()
         execute('later 1h')
         expect_line('123456abc')
       end
+
+      -- Retry up to 3 times. pcall() is _not_ used for the final attempt, so
+      -- that failure messages can bubble up.
       local success, result = false, ''
       for i = 1, 2 do
         success, result = pcall(test_earlier_later)
@@ -107,13 +109,10 @@ describe('undo:', function()
           return
         end
       end
-      -- We did not return in the loop so there was an error or failure.
-      -- We now try to run the test again but will not catch further errors,
-      -- so the user will see them.
       test_earlier_later()
     end)
 
-    it('work with file write specifications', function()
+    it('file-write specifications', function()
       feed('ione one one<esc>')
       execute('w Xtest')
       feed('otwo<esc>')
@@ -145,7 +144,7 @@ describe('undo:', function()
     end)
   end)
 
-  it('scripts produce one undo block for all changes by default', function()
+  it('scripts produce one undo-block for all changes by default', function()
     source([[
       normal Aaaaa
       normal obbbb
@@ -159,9 +158,9 @@ describe('undo:', function()
     expect_empty_buffer()
   end)
 
-  it('setting undolevel can break change blocks (inside scripts)', function()
-    -- We need to use source() in order to test this, as interactive changes
-    -- are not grouped.
+  it("setting 'undolevel' can break undo-blocks (inside scripts)", function()
+    -- :source is required (because interactive changes are _not_ grouped,
+    -- even with :undojoin).
     source([[
       normal Aaaaa
       set ul=100
@@ -183,7 +182,7 @@ describe('undo:', function()
     expect_empty_buffer()
   end)
 
-  it(':undojoin can join change blocks inside scripts', function()
+  it(':undojoin can join undo-blocks inside scripts', function()
     feed('Goaaaa<esc>')
     feed('obbbb<esc>u')
     expect_line('aaaa')
@@ -197,7 +196,7 @@ describe('undo:', function()
     expect_line('aaaa')
   end)
 
-  it('undoing pastes from the expression register is working', function()
+  it('undo an expression-register', function()
     local normal_commands = 'o1\x1ba2\x12=string(123)\n\x1b'
     write_file('Xtest.source', normal_commands)
 
@@ -252,9 +251,10 @@ describe('undo:', function()
       c
       12
       d]])
-    -- The above behaviour was tested in the legacy vim test because the
+
+    -- The above behaviour was tested in the legacy Vim test because the
     -- legacy tests were executed with ':so!'.  The behavior differs for
-    -- interactive use (even in vim, where the result was the same):
+    -- interactive use (even in Vim; see ":help :undojoin"):
     feed(normal_commands)
     expect([[