patch 8.0.0763: libvterm can be improved

Problem:    Libvterm can be improved.
Solution:   Various small improvements, more comments.

8 files changed, 26 insertions, 15 deletions

diff --git a/src/libvterm/README b/src/libvterm/README
index ef74b011a..8d4de3933 100644
--- a/src/libvterm/README
+++ b/src/libvterm/README
@@ -1,13 +1,12 @@
 This is a MODIFIED version of libvterm.
 
 The original can be found:
-On the original site (tar archive and Bazaar repository):
+- on the original site (tar archive and Bazaar repository):
 	http://www.leonerd.org.uk/code/libvterm/
-Cloned on Github:
+- cloned on Github:
 	https://github.com/neovim/libvterm
 
 Modifications:
 - Add a .gitignore file.
 - Convert from C99 to C90.
 - Other changes to support embedding in Vim.
-- 
diff --git a/src/libvterm/include/vterm.h b/src/libvterm/include/vterm.h
index 1aa646337..5bc47e513 100644
--- a/src/libvterm/include/vterm.h
+++ b/src/libvterm/include/vterm.h
@@ -160,7 +160,9 @@ VTerm *vterm_new_with_allocator(int rows, int cols, VTermAllocatorFunctions *fun
 /* Free and cleanup a terminal and all its data. */
 void   vterm_free(VTerm* vt);
 
+/* Get the current size of the terminal and store in "rowsp" and "colsp". */
 void vterm_get_size(const VTerm *vt, int *rowsp, int *colsp);
+
 void vterm_set_size(VTerm *vt, int rows, int cols);
 
 int  vterm_get_utf8(const VTerm *vt);
@@ -195,14 +197,14 @@ void vterm_mouse_button(VTerm *vt, int button, bool pressed, VTermModifier mod);
  *
  * Don't confuse this with the final byte of the CSI escape; 'a' in this case.
  */
-#define CSI_ARG_FLAG_MORE (1<<31)
-#define CSI_ARG_MASK      (~(1<<31))
+#define CSI_ARG_FLAG_MORE (1<<30)
+#define CSI_ARG_MASK      (~(1<<30))
 
 #define CSI_ARG_HAS_MORE(a) ((a) & CSI_ARG_FLAG_MORE)
 #define CSI_ARG(a)          ((a) & CSI_ARG_MASK)
 
 /* Can't use -1 to indicate a missing argument; use this instead */
-#define CSI_ARG_MISSING ((1UL<<31)-1)
+#define CSI_ARG_MISSING ((1<<30)-1)
 
 #define CSI_ARG_IS_MISSING(a) (CSI_ARG(a) == CSI_ARG_MISSING)
 #define CSI_ARG_OR(a,def)     (CSI_ARG(a) == CSI_ARG_MISSING ? (def) : CSI_ARG(a))
@@ -248,7 +250,9 @@ void *vterm_state_get_cbdata(VTermState *state);
 void  vterm_state_set_unrecognised_fallbacks(VTermState *state, const VTermParserCallbacks *fallbacks, void *user);
 void *vterm_state_get_unrecognised_fbdata(VTermState *state);
 
+/* Initialize the state. */
 void vterm_state_reset(VTermState *state, int hard);
+
 void vterm_state_get_cursorpos(const VTermState *state, VTermPos *cursorpos);
 void vterm_state_get_default_colors(const VTermState *state, VTermColor *default_fg, VTermColor *default_bg);
 void vterm_state_get_palette_color(const VTermState *state, int index, VTermColor *col);
@@ -295,6 +299,7 @@ typedef struct {
   int (*sb_popline)(int cols, VTermScreenCell *cells, void *user);
 } VTermScreenCallbacks;
 
+/* Return the screen of the vterm. */
 VTermScreen *vterm_obtain_screen(VTerm *vt);
 
 /*
@@ -317,9 +322,15 @@ typedef enum {
   VTERM_DAMAGE_SCROLL   /* entire screen + scrollrect */
 } VTermDamageSize;
 
+/* Invoke the relevant callbacks to update the screen. */
 void vterm_screen_flush_damage(VTermScreen *screen);
+
 void vterm_screen_set_damage_merge(VTermScreen *screen, VTermDamageSize size);
 
+/*
+ * Reset the screen.  Also invokes vterm_state_reset().
+ * Must be called before the terminal can be used.
+ */
 void   vterm_screen_reset(VTermScreen *screen, int hard);
 
 /* Neither of these functions NUL-terminate the buffer */
diff --git a/src/libvterm/include/vterm_keycodes.h b/src/libvterm/include/vterm_keycodes.h
index c575254a4..7a7791696 100644
--- a/src/libvterm/include/vterm_keycodes.h
+++ b/src/libvterm/include/vterm_keycodes.h
@@ -28,9 +28,11 @@ typedef enum {
   VTERM_KEY_PAGEUP,
   VTERM_KEY_PAGEDOWN,
 
+  /* F1 is VTERM_KEY_FUNCTION(1), F2 VTERM_KEY_FUNCTION(2), etc. */
   VTERM_KEY_FUNCTION_0   = 256,
   VTERM_KEY_FUNCTION_MAX = VTERM_KEY_FUNCTION_0 + 255,
 
+  /* keypad keys */
   VTERM_KEY_KP_0,
   VTERM_KEY_KP_1,
   VTERM_KEY_KP_2,
diff --git a/src/libvterm/src/keyboard.c b/src/libvterm/src/keyboard.c
index e154a08a7..e99039d84 100644
--- a/src/libvterm/src/keyboard.c
+++ b/src/libvterm/src/keyboard.c
@@ -68,6 +68,7 @@ typedef struct {
   int csinum;
 } keycodes_s;
 
+/* Order here must be exactly the same as VTermKey enum! */
 static keycodes_s keycodes[] = {
   { KEYCODE_NONE,       0, 0 }, /* NONE */
 
diff --git a/src/libvterm/src/parser.c b/src/libvterm/src/parser.c
index 380f91651..74556dce4 100644
--- a/src/libvterm/src/parser.c
+++ b/src/libvterm/src/parser.c
@@ -190,7 +190,7 @@ static size_t do_string(VTerm *vt, const char *str_frag, size_t len)
 size_t vterm_input_write(VTerm *vt, const char *bytes, size_t len)
 {
   size_t pos = 0;
-  const char *string_start;
+  const char *string_start = NULL;  /* init to avoid gcc warning */
 
   switch(vt->parser_state) {
   case NORMAL:
diff --git a/src/libvterm/src/screen.c b/src/libvterm/src/screen.c
index ef13f3dcc..a174e8657 100644
--- a/src/libvterm/src/screen.c
+++ b/src/libvterm/src/screen.c
@@ -819,14 +819,9 @@ int vterm_screen_is_eol(const VTermScreen *screen, VTermPos pos)
 
 VTermScreen *vterm_obtain_screen(VTerm *vt)
 {
-  VTermScreen *screen;
-  if(vt->screen)
-    return vt->screen;
-
-  screen = screen_new(vt);
-  vt->screen = screen;
-
-  return screen;
+  if(!vt->screen)
+    vt->screen = screen_new(vt);
+  return vt->screen;
 }
 
 void vterm_screen_enable_altscreen(VTermScreen *screen, int altscreen)
diff --git a/src/libvterm/src/state.c b/src/libvterm/src/state.c
index 1b7e89d31..0c685309d 100644
--- a/src/libvterm/src/state.c
+++ b/src/libvterm/src/state.c
@@ -1194,6 +1194,7 @@ static int on_csi(const char *leader, const long args[], int argcount, const cha
     break;
 
   case LEADER('>', 0x63): /* DEC secondary Device Attributes */
+    /* This returns xterm version number 100. */
     vterm_push_output_sprintf_ctrl(state->vt, C1_CSI, ">%d;%d;%dc", 0, 100, 0);
     break;
 
diff --git a/src/version.c b/src/version.c
index c34407281..e2ab84c3c 100644
--- a/src/version.c
+++ b/src/version.c
@@ -770,6 +770,8 @@ static char *(features[]) =
 static int included_patches[] =
 {   /* Add new patch number below this line */
 /**/
+    763,
+/**/
     762,
 /**/
     761,