patch 8.2.0158: triggering CompleteDone earlier is not backwards compatible

Problem:    Triggering CompleteDone earlier is not backwards compatible.
            (Daniel Hahler)
Solution:   Add CompleteDonePre instead.

runtime/doc/autocmd.txt

@@ -374,7 +374,10 @@ Name			triggered by ~
 
 |MenuPopup|		just before showing the popup menu
 |CompleteChanged|	after Insert mode completion menu changed
-|CompleteDone|		after Insert mode completion is done
+|CompleteDonePre|	after Insert mode completion is done, before clearing
+			info
+|CompleteDone|		after Insert mode completion is done, after clearing
+			info
 
 |User|			to be used in combination with ":doautocmd"
 
@@ -589,8 +592,8 @@ ColorSchemePre			Before loading a color scheme. |:colorscheme|
 CompleteChanged						*CompleteChanged*
 				After each time the Insert mode completion
 				menu changed.  Not fired on popup menu hide,
-				use |CompleteDone| for that.  Never triggered
+				use |CompleteDonePre| or |CompleteDone| for
-				recursively.
+				that.  Never triggered recursively.
 
 				Sets these |v:event| keys:
 				    completed_item	See |complete-items|.
@@ -606,12 +609,22 @@ CompleteChanged						*CompleteChanged*
 				The size and position of the popup are also
 				available by calling |pum_getpos()|.
 
+							*CompleteDonePre*
+CompleteDonePre			After Insert mode completion is done.  Either
+				when something was completed or abandoning
+				completion. |ins-completion|
+				|complete_info()| can be used, the info is
+				cleared after triggering CompleteDonePre.
+				The |v:completed_item| variable contains
+				information about the completed item.
+
 							*CompleteDone*
 CompleteDone			After Insert mode completion is done.  Either
 				when something was completed or abandoning
 				completion. |ins-completion|
-				|complete_info()| can be used, the info is
+				|complete_info()| cannot be used, the info is
-				cleared after triggering CompleteDone.
+				cleared before triggering CompleteDone.  Use
+				CompleteDonePre if you need it.
 				The |v:completed_item| variable contains
 				information about the completed item.
 

src/autocmd.c

@@ -114,6 +114,7 @@ static struct event_name
     {"ColorSchemePre",	EVENT_COLORSCHEMEPRE},
     {"CompleteChanged",	EVENT_COMPLETECHANGED},
     {"CompleteDone",	EVENT_COMPLETEDONE},
+    {"CompleteDonePre",	EVENT_COMPLETEDONEPRE},
     {"CursorHold",	EVENT_CURSORHOLD},
     {"CursorHoldI",	EVENT_CURSORHOLDI},
     {"CursorMoved",	EVENT_CURSORMOVED},

src/insexpand.c

@@ -2061,12 +2061,11 @@ ins_compl_prep(int c)
 
 	    auto_format(FALSE, TRUE);
 
-	    // Trigger the CompleteDone event to give scripts a chance to
+	    // Trigger the CompleteDonePre event to give scripts a chance to
-	    // act upon the completion.  Do this before clearing the info,
+	    // act upon the completion before clearing the info, and restore
-	    // and restore ctrl_x_mode, so that complete_info() can be
+	    // ctrl_x_mode, so that complete_info() can be used.
-	    // used.
 	    ctrl_x_mode = prev_mode;
-	    ins_apply_autocmds(EVENT_COMPLETEDONE);
+	    ins_apply_autocmds(EVENT_COMPLETEDONEPRE);
 
 	    ins_compl_free();
 	    compl_started = FALSE;
@@ -2092,6 +2091,9 @@ ins_compl_prep(int c)
 	    if (want_cindent && in_cinkeys(KEY_COMPLETE, ' ', inindent(0)))
 		do_c_expr_indent();
 #endif
+	    // Trigger the CompleteDone event to give scripts a chance to act
+	    // upon the end of completion.
+	    ins_apply_autocmds(EVENT_COMPLETEDONE);
 	}
     }
     else if (ctrl_x_mode == CTRL_X_LOCAL_MSG)

src/testdir/test_ins_complete.vim

@@ -175,7 +175,7 @@ func s:CompleteDone_CheckCompletedItemNone()
   let s:called_completedone = 1
 endfunc
 
-func s:CompleteDone_CheckCompletedItemDict()
+func s:CompleteDone_CheckCompletedItemDict(pre)
   call assert_equal( 'aword',          v:completed_item[ 'word' ] )
   call assert_equal( 'wrd',            v:completed_item[ 'abbr' ] )
   call assert_equal( 'extra text',     v:completed_item[ 'menu' ] )
@@ -183,7 +183,9 @@ func s:CompleteDone_CheckCompletedItemDict()
   call assert_equal( 'W',              v:completed_item[ 'kind' ] )
   call assert_equal( 'test',           v:completed_item[ 'user_data' ] )
 
+  if a:pre
     call assert_equal('function', complete_info().mode)
+  endif
 
   let s:called_completedone = 1
 endfunc
@@ -205,7 +207,8 @@ func Test_CompleteDoneNone()
 endfunc
 
 func Test_CompleteDoneDict()
-  au CompleteDone * :call <SID>CompleteDone_CheckCompletedItemDict()
+  au CompleteDonePre * :call <SID>CompleteDone_CheckCompletedItemDict(1)
+  au CompleteDone * :call <SID>CompleteDone_CheckCompletedItemDict(0)
 
   set completefunc=<SID>CompleteDone_CompleteFuncDict
   execute "normal a\<C-X>\<C-U>\<C-Y>"

src/version.c

@@ -742,6 +742,8 @@ static char *(features[]) =
 
 static int included_patches[] =
 {   /* Add new patch number below this line */
+/**/
+    158,
 /**/
     157,
 /**/

src/vim.h

@@ -1303,6 +1303,7 @@ enum auto_event
     EVENT_COLORSCHEMEPRE,	// before loading a colorscheme
     EVENT_COMPLETECHANGED,	// after completion popup menu changed
     EVENT_COMPLETEDONE,		// after finishing insert complete
+    EVENT_COMPLETEDONEPRE,	// idem, before clearing info
     EVENT_CURSORHOLD,		// cursor in same position for a while
     EVENT_CURSORHOLDI,		// idem, in Insert mode
     EVENT_CURSORMOVED,		// cursor was moved