From f59f81c32e901b5f6990bbe0b5608c073c0b1b9c Mon Sep 17 00:00:00 2001
From: zeertzjq <zeertzjq@outlook.com>
Date: Thu, 16 Dec 2021 23:05:52 +0800
Subject: [PATCH] vim-patch:8.2.3825: various comments could be improved

Problem:    Various comments could be improved.
Solution:   Improve the comments.
https://github.com/vim/vim/commit/52797bae1710621926c03a2611c40a692c96fb44
---
 src/nvim/getchar.c             |  4 ++--
 src/nvim/mbyte.c               | 10 +++++-----
 src/nvim/regexp_nfa.c          | 30 ++++++++++++++----------------
 src/nvim/testdir/test_edit.vim |  3 +++
 4 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/src/nvim/getchar.c b/src/nvim/getchar.c
index 05c38a52334c58..6b1150cefaf97e 100644
--- a/src/nvim/getchar.c
+++ b/src/nvim/getchar.c
@@ -1894,7 +1894,7 @@ static int handle_mapping(int *keylenp, bool *timedout, int *mapdepth)
     // buffer right here. Otherwise, use the mapping (loop around).
     if (mp == NULL) {
       *keylenp = keylen;
-      return map_result_get;  // got character, break for loop
+      return map_result_get;  // get character from typeahead
     } else {
       keylen = mp_match_len;
     }
@@ -2166,7 +2166,7 @@ static int vgetorpeek(bool advance)
               KeyNoremap = typebuf.tb_noremap[typebuf.tb_off];
               del_typebuf(1, 0);
             }
-            break;
+            break;  // got character, break the for loop
           }
 
           // not enough characters, get more
diff --git a/src/nvim/mbyte.c b/src/nvim/mbyte.c
index ce44f6c619bdf1..5eb209a6f6ea64 100644
--- a/src/nvim/mbyte.c
+++ b/src/nvim/mbyte.c
@@ -1609,7 +1609,8 @@ void show_utf8(void)
   msg((char *)IObuff);
 }
 
-/// Return offset from "p" to the first byte of the character it points into.
+/// Return offset from "p" to the start of a character, including composing characters.
+/// "base" must be the start of the string, which must be NUL terminated.
 /// If "p" points to the NUL at the end of the string return 0.
 /// Returns 0 when already at the first byte of a character.
 int utf_head_off(const char_u *base, const char_u *p)
@@ -1850,10 +1851,9 @@ int mb_off_next(char_u *base, char_u *p)
   return i;
 }
 
-/*
- * Return the offset from "p" to the last byte of the character it points
- * into.  Can start anywhere in a stream of bytes.
- */
+/// Return the offset from "p" to the last byte of the character it points
+/// into.  Can start anywhere in a stream of bytes.
+/// Composing characters are not included.
 int mb_tail_off(char_u *base, char_u *p)
 {
   int i;
diff --git a/src/nvim/regexp_nfa.c b/src/nvim/regexp_nfa.c
index 3e7306bad319df..eac1b4596ed0ea 100644
--- a/src/nvim/regexp_nfa.c
+++ b/src/nvim/regexp_nfa.c
@@ -18,22 +18,20 @@
 #include "nvim/garray.h"
 #include "nvim/os/input.h"
 
-/*
- * Logging of NFA engine.
- *
- * The NFA engine can write four log files:
- * - Error log: Contains NFA engine's fatal errors.
- * - Dump log: Contains compiled NFA state machine's information.
- * - Run log: Contains information of matching procedure.
- * - Debug log: Contains detailed information of matching procedure. Can be
- *   disabled by undefining NFA_REGEXP_DEBUG_LOG.
- * The first one can also be used without debug mode.
- * The last three are enabled when compiled as debug mode and individually
- * disabled by commenting them out.
- * The log files can get quite big!
- * Do disable all of this when compiling Vim for debugging, undefine REGEXP_DEBUG in
- * regexp.c
- */
+// Logging of NFA engine.
+//
+// The NFA engine can write four log files:
+// - Error log: Contains NFA engine's fatal errors.
+// - Dump log: Contains compiled NFA state machine's information.
+// - Run log: Contains information of matching procedure.
+// - Debug log: Contains detailed information of matching procedure. Can be
+//   disabled by undefining NFA_REGEXP_DEBUG_LOG.
+// The first one can also be used without debug mode.
+// The last three are enabled when compiled as debug mode and individually
+// disabled by commenting them out.
+// The log files can get quite big!
+// To disable all of this when compiling Vim for debugging, undefine REGEXP_DEBUG in
+// regexp.c
 #ifdef REGEXP_DEBUG
 # define NFA_REGEXP_ERROR_LOG   "nfa_regexp_error.log"
 # define NFA_REGEXP_DUMP_LOG    "nfa_regexp_dump.log"
diff --git a/src/nvim/testdir/test_edit.vim b/src/nvim/testdir/test_edit.vim
index 37786f3ca0bcb0..fc4e80f0d6652a 100644
--- a/src/nvim/testdir/test_edit.vim
+++ b/src/nvim/testdir/test_edit.vim
@@ -1294,6 +1294,7 @@ func Test_edit_forbidden()
   call assert_fails(':Sandbox', 'E48:')
   delcom Sandbox
   call assert_equal(['a'], getline(1,'$'))
+
   " 2) edit with textlock set
   fu! DoIt()
     call feedkeys("i\<del>\<esc>", 'tnix')
@@ -1313,6 +1314,7 @@ func Test_edit_forbidden()
   catch /^Vim\%((\a\+)\)\=:E117/ " catch E117: unknown function
   endtry
   au! InsertCharPre
+
   " 3) edit when completion is shown
   fun! Complete(findstart, base)
     if a:findstart
@@ -1330,6 +1332,7 @@ func Test_edit_forbidden()
   endtry
   delfu Complete
   set completefunc=
+
   if has("rightleft") && exists("+fkmap")
     " 4) 'R' when 'fkmap' and 'revins' is set.
     set revins fkmap