format comments to fit screen and be readable

history-substring-search.zsh

@@ -60,28 +60,34 @@
 #
 ##############################################################################
 
-# IMPORTANT / NOTE THAT:
+# NOTE: The "up" in "up-history()" corresponds to "backward"
-# "up" (in e.g. "up-history()" corresponds with "backward" (in e.g. "history-substring-search-backward()"
+#       in "history-substring-search-backward()", and so on.
-# "down" (in e.g. "down-history()" corresponds with "forward" (in e.g. "history-substring-search-forward()"
+#
+# NOTE: The "down" in "down-history()" corresponds to "forward"
+#       in "history-substring-search-forward()", and so on.
 
 setopt extendedglob
 zmodload -F zsh/parameter
 
-# We have to "override" some keys and widgets, unless
+#
-# the zsh-syntax-highlighting plugin has been loaded:
+# We have to "override" some keys and widgets if the
+# zsh-syntax-highlighting plugin has not been loaded:
 #
 # https://github.com/nicoulaj/zsh-syntax-highlighting
 #
 if [[ $+functions[_zsh_highlight] -eq 0 ]]; then
-
+  #
   # Dummy implementation of _zsh_highlight()
   # that simply removes existing highlights
+  #
   function _zsh_highlight() {
     region_highlight=()
   }
 
+  #
   # Remove existing highlights when the user
   # inserts printable characters into $BUFFER
+  #
   function ordinary-key-press() {
     if [[ $KEYS = [[:print:]] ]]; then
       region_highlight=()
@@ -90,6 +96,7 @@ if [[ $+functions[_zsh_highlight] -eq 0 ]]; then
   }
   zle -N self-insert ordinary-key-press
 
+  #
   # Override ZLE widgets to invoke _zsh_highlight()
   #
   # https://github.com/nicoulaj/zsh-syntax-highlighting/blob/
@@ -172,46 +179,59 @@ HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND='bg=red,fg=white,bold'
 HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS='i' # "i" means case insensitive, see "Globbing Flags" in zshexpn(1)
 
 _history-substring-search-begin() {
-
+  #
   # Continue using the previous $_history_substring_search_result by default,
   # unless the current query was cleared or a new/different query was entered.
+  #
   if [[ -z $BUFFER || $BUFFER != $_history_substring_search_result ]]; then
+    #
+    # For the purpose of highlighting we will also keep
+    # a version without doubly-escaped meta characters.
+    #
+    _history_substring_search_query=$BUFFER
 
-    # BUFFER contains the text that is in the command-line currently.
+    #
+    # $BUFFER contains the text that is in the command-line currently.
     # we put an extra "\\" before meta characters such as "\(" and "\)",
     # so that they become "\\\(" and "\\\)".
+    #
     _history_substring_search_query_escaped=${BUFFER//(#m)[\][()|\\*?#<>~^]/\\$MATCH}
 
-    # For the purpose of highlighting we will also keep a version without
+    #
-    # doubly-escaped meta characters.
+    # Find all occurrences of the search query in the history file.
-    _history_substring_search_query=${BUFFER}
+    #
-
-    # Find all occurrences of the pattern *${_history_substring_search_query}* within the history file.
     # (k) turns it an array of line numbers.
-    # (on) seems to remove duplicates, which are default options. They can be turned off by (ON).
+    #
+    # (on) seems to remove duplicates, which are default
+    #      options. They can be turned off by (ON).
+    #
     _history_substring_search_matches=(${(kon)history[(R)(#$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)*${_history_substring_search_query_escaped}*]})
 
+    #
     # Define the range of values that $_history_substring_search_match_number
     # can take: [0, $_history_substring_search_number_of_matches_plus_one].
+    #
     _history_substring_search_number_of_matches=${#_history_substring_search_matches}
     let "_history_substring_search_number_of_matches_plus_one = $_history_substring_search_number_of_matches + 1"
     let "_history_substring_search_number_of_matches_minus_one = $_history_substring_search_number_of_matches - 1"
 
-    # initial value of $_history_substring_search_match_number, which can
+    #
-    # only be decreased by ${WIDGET/forward/backward}.
+    # initial value of $_history_substring_search_match_number,
+    # which can only be decreased by ${WIDGET/forward/backward}.
+    #
     let "_history_substring_search_match_number = $_history_substring_search_number_of_matches_plus_one"
   fi
 }
 
 _history-substring-search-highlight() {
   _zsh_highlight
-  if [[ -n $_history_substring_search_query ]]; then
 
-    # $_history_substring_search_query_escaped string was not empty.
+  if [[ -n $_history_substring_search_query ]]; then
-    # So, highlight it:
+    #
-    # The following expression yields a variable $MBEGIN,
+    # The following expression yields a variable $MBEGIN, which
-    # which indicates the begin position + 1 of the first occurrence of
+    # indicates the begin position + 1 of the first occurrence
-    # _history_substring_search_query_escaped in $BUFFER.
+    # of _history_substring_search_query_escaped in $BUFFER.
+    #
     : ${(S)BUFFER##(#m$HISTORY_SUBSTRING_SEARCH_GLOBBING_FLAGS)($_history_substring_search_query##)}
     let "_history_substring_search_query_mbegin = $MBEGIN - 1"
     let "_history_substring_search_query_mend = $_history_substring_search_query_mbegin + $#_history_substring_search_query"
@@ -220,7 +240,7 @@ _history-substring-search-highlight() {
 }
 
 _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer() {
-
+  #
   # Check if the UP arrow was pressed to move the cursor within a multi-line
   # buffer. This amounts to three tests:
   #
@@ -231,20 +251,23 @@ _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer()
   # 3. Check if we are on the first line of the current multi-line buffer.
   #    If so, pressing UP would amount to leaving the multi-line buffer.
   #
-  #    We check this by adding an extra "x" to $LBUFFER, which makes sure that
+  #    We check this by adding an extra "x" to $LBUFFER, which makes
-  #    xlbuflines is always equal to the number of lines until $CURSOR
+  #    sure that xlbuflines is always equal to the number of lines
-  #    (including the line with the cursor on it).
+  #    until $CURSOR (including the line with the cursor on it).
   #
   buflines=(${(f)BUFFER})
   local XLBUFFER=$LBUFFER"x"
   xlbuflines=(${(f)XLBUFFER})
+
   if [[ $#buflines -gt 1 && $CURSOR -ne $#BUFFER && $#xlbuflines -ne 1 ]]; then
     zle up-line-or-history
     _history_substring_search_move_cursor_eol=false
-
+    #
-    # $_history_substring_search_move_up_within_mutiline_buffer should reflect whether the call to
+    # $_history_substring_search_move_up_within_mutiline_buffer should reflect
+    # whether the call to
     # _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer()
     # has succeeded or failed:
+    #
     _history_substring_search_move_up_within_mutiline_buffer=true
   else
     _history_substring_search_move_up_within_mutiline_buffer=false
@@ -252,7 +275,7 @@ _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer()
 }
 
 _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer() {
-
+  #
   # Check if the DOWN arrow was pressed to move the cursor within a multi-line
   # buffer. This amounts to three tests:
   #
@@ -263,20 +286,23 @@ _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer
   # 3. Check if we are on the last line of the current multi-line buffer.
   #    If so, pressing DOWN would amount to leaving the multi-line buffer.
   #
-  #    We check this by adding an extra "x" to $RBUFFER, which makes sure that
+  #    We check this by adding an extra "x" to $RBUFFER, which makes
-  #    xrbuflines is always equal to the number of lines from $CURSOR
+  #    sure that xrbuflines is always equal to the number of lines
-  #    (including the line with the cursor on it).
+  #    from $CURSOR (including the line with the cursor on it).
   #
   buflines=(${(f)BUFFER})
   local XRBUFFER="x"$RBUFFER
   xrbuflines=(${(f)XRBUFFER})
+
   if [[ $#buflines -gt 1 && $CURSOR -ne $#BUFFER && $#xrbuflines -ne 1 ]]; then
     zle down-line-or-history
     _history_substring_search_move_cursor_eol=false
-
+    #
-    # $_history_substring_search_move_down_within_mutiline_buffer should reflect whether the call to
+    # $_history_substring_search_move_down_within_mutiline_buffer should
+    # reflect whether the call to
     # _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer()
     # has succeeded or failed:
+    #
     _history_substring_search_move_down_within_mutiline_buffer=true
   else
     _history_substring_search_move_down_within_mutiline_buffer=false
@@ -284,22 +310,26 @@ _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer
 }
 
 _history-substring-search-check-up-history() {
-
+  #
-  # When searching without a search query history-substring-search-backward should behave like
+  # When searching without a search query history-substring-search-backward
-  # up-history. Apart from this such a search should end with an empty BUFFER like in Fish.
+  # should behave like up-history. Apart from this, such a search should end
-  if [[ $_history_substring_search_query == "" ]]; then
+  # with an empty $BUFFER like in Fish.
-
+  #
+  if [[ -z $_history_substring_search_query ]]; then
     # As long as we are not at the last history entry, call up-history():
     if [[ $HISTNO -gt 1 ]]; then
       zle up-history
     else
-
+      #
-      # [[ $HISTNO -eq 1 ]] means that _history-substring-search-check-UP-history() has arrived
+      # [[ $HISTNO -eq 1 ]] means that
-      # at the last entry of the history file.
+      # _history-substring-search-check-UP-history() has arrived at the last
-      # In that case we make $_history_substring_search_last_entry_in_history equal to $BUFFER.
+      # entry of the history file.  In that case we make
-      # This value can later be retrieved by _history-substring-search-check-DOWN-history().
+      # $_history_substring_search_last_entry_in_history equal to $BUFFER.
-      # Moreover the current buffer should be made empty.
+      # This value can later be retrieved by
-      # In all other cases $_history_substring_search_last_entry_in_history should remain empty:
+      # _history-substring-search-check-DOWN-history().  Moreover the current
+      # buffer should be made empty.  In all other cases
+      # $_history_substring_search_last_entry_in_history should remain empty:
+      #
       [[ $#_history_substring_search_last_entry_in_history -eq 0 ]] && _history_substring_search_last_entry_in_history=$BUFFER
       BUFFER=""
     fi
@@ -313,30 +343,35 @@ _history-substring-search-check-up-history() {
 }
 
 _history-substring-search-check-down-history() {
-
+  #
-  # When searching without a search query the widget history-substring-search-forward should behave like
+  # When searching without a search query the widget
-  # down-history. Apart from this such a search should end with an empty buffer:
+  # history-substring-search-forward should behave like down-history. Apart
-  if [[ $_history_substring_search_query == "" ]]; then
+  # from this, such a search should end with an empty buffer:
-
+  #
-    # If _history-substring-search-check-UP-history() has previously arrived at the last history entry
+  if [[ -z $_history_substring_search_query ]]; then
-    # it will have made $_history_substring_search_last_entry_in_history equal to $BUFFER
+    #
-    # (see the description of _history-substring-search-check-UP-history()).
+    # If _history-substring-search-check-UP-history() has previously arrived
-    # Therefore, here we test if $_history_substring_search_last_entry_in_history is equal
+    # at the last history entry it will have made
-    # to an empty string:
+    # $_history_substring_search_last_entry_in_history equal to $BUFFER (see
+    # the description of _history-substring-search-check-UP-history()).
+    # Therefore, here we test if
+    # $_history_substring_search_last_entry_in_history is equal to an empty
+    # string:
+    #
     if [[ $#_history_substring_search_last_entry_in_history -eq 0 ]]; then
-
       # If so we can safely call down-history():
       zle down-history
     else
-
+      # If not we make $BUFFER equal to
-      # If not we make $BUFFER equal to $_history_substring_search_last_entry_in_history
+      # $_history_substring_search_last_entry_in_history and we move the the
-      # and we move the the cursor to the end of the buffer:
+      # cursor to the end of the buffer:
       BUFFER=$_history_substring_search_last_entry_in_history
       CURSOR=$#BUFFER
 
-      # And we make $_history_substring_search_last_entry_in_history equal to an empty string,
+      # And we make $_history_substring_search_last_entry_in_history equal to
-      # so that later we will be able to call up-history() and down-history() again:
+      # an empty string, so that later we will be able to call up-history()
-      _history_substring_search_last_entry_in_history=""
+      # and down-history() again:
+      _history_substring_search_last_entry_in_history=''
     fi
 
     # $_history_substring_search_down_history should reflect whether
@@ -348,110 +383,159 @@ _history-substring-search-check-down-history() {
 }
 
 _history-substring-search-highlight-matches-up() {
-  # Highlight matches during a history-backward-search:
   #
-  # $_history_substring_search_matches: the current list of matches
+  # Highlight matches during a history-substring-search:
-  # $_history_substring_search_number_of_matches: the current number of matches
+  #
-  # $_history_substring_search_number_of_matches_plus_one: the current number of matches + 1
+  # * $_history_substring_search_matches: the current list of matches
-  # $_history_substring_search_number_of_matches_minus_one: the current number of matches - 1
+  # * $_history_substring_search_number_of_matches: the current number of matches
-  # $_history_substring_search_match_number: the number of the current match
+  # * $_history_substring_search_number_of_matches_plus_one: the current number of matches + 1
-
+  # * $_history_substring_search_number_of_matches_minus_one: the current number of matches - 1
-  # The range of values that $_history_substring_search_match_number can take is:
+  # * $_history_substring_search_match_number: the number of the current match
-  # [0, $_history_substring_search_number_of_matches_plus_one].
+  #
-  # A value of 0 indicates that we are beyond the end of $_history_substring_search_matches.
+  # The range of values that $_history_substring_search_match_number can take
-  # A value of $_history_substring_search_number_of_matches_plus_one indicates that we are beyond
+  # is: [0, $_history_substring_search_number_of_matches_plus_one].  A value
-  # the beginning of $_history_substring_search_matches.
+  # of 0 indicates that we are beyond the end of
-
+  # $_history_substring_search_matches.  A value of
-  # The initial value of $_history_substring_search_match_number is $_history_substring_search_number_of_matches_plus_one.
+  # $_history_substring_search_number_of_matches_plus_one indicates that we
-
+  # are beyond the beginning of $_history_substring_search_matches.
+  #
+  # The initial value of $_history_substring_search_match_number is
+  # $_history_substring_search_number_of_matches_plus_one.
+  #
   if [[ $_history_substring_search_match_number -ge 2 ]]; then
-
+    #
     # Highlight the next match:
-    # 1) Decrease the value of $_history_substring_search_match_number.
+    #
-    # 2) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer.
+    # 1. Decrease the value of $_history_substring_search_match_number.
+    #
+    # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+    #    to highlight the current buffer.
+    #
     let "_history_substring_search_match_number = $_history_substring_search_match_number - 1"
     BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_number]]
     _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
-  elif [[ $_history_substring_search_match_number -eq 1 ]]; then
 
+  elif [[ $_history_substring_search_match_number -eq 1 ]]; then
+    #
     # We will move beyond the end of $_history_substring_search_matches:
-    # 1) Decrease the value of $_history_substring_search_match_number.
+    #
-    # 2) Save the current buffer in $_history_substring_search_old_buffer, so that it can be retrieved by
+    # 1. Decrease the value of $_history_substring_search_match_number.
+    #
+    # 2. Save the current buffer in $_history_substring_search_old_buffer,
+    #    so that it can be retrieved by
     #    _history-substring-search-highlight-matches-down() later.
-    # 3) Make $BUFFER equal to $_history_substring_search_query.
+    #
-    # 4) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND to highlight the current buffer.
+    # 3. Make $BUFFER equal to $_history_substring_search_query.
+    #
+    # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
+    #    to highlight the current buffer.
+    #
     let "_history_substring_search_match_number = $_history_substring_search_match_number - 1"
     _history_substring_search_old_buffer=$BUFFER
     BUFFER=$_history_substring_search_query
     _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
-  elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches_plus_one ]]; then
 
-    # We were beyond the beginning of $_history_substring_search_matches but UP makes us
+  elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches_plus_one ]]; then
-    # move back to $_history_substring_search_matches:
+    #
-    # 1) Decrease the value $of _history_substring_search_match_number.
+    # We were beyond the beginning of $_history_substring_search_matches but
-    # 2) Restore $BUFFER from $_history_substring_search_old_buffer.
+    # UP makes us move back to $_history_substring_search_matches:
-    # 3) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer.
+    #
+    # 1. Decrease the value $of _history_substring_search_match_number.
+    #
+    # 2. Restore $BUFFER from $_history_substring_search_old_buffer.
+    #
+    # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+    #    to highlight the current buffer.
+    #
     let "_history_substring_search_match_number = $_history_substring_search_match_number - 1"
     BUFFER=$_history_substring_search_old_buffer
     _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
   fi
+
   _history_substring_search_move_cursor_eol=true
 }
 
 _history-substring-search-highlight-matches-down() {
-
+  #
-  # Highlight matches during a history-backward-search:
+  # Highlight matches during a history-substring-search:
   #
   # $_history_substring_search_matches: the current list of matches
   # $_history_substring_search_number_of_matches: the current number of matches
   # $_history_substring_search_number_of_matches_plus_one: the current number of matches + 1
   # $_history_substring_search_number_of_matches_minus_one: the current number of matches - 1
   # $_history_substring_search_match_number: the number of the current match
-
+  #
-  # The range of values that $_history_substring_search_match_number can take is:
+  # The range of values that $_history_substring_search_match_number can take
-  # [0, $_history_substring_search_number_of_matches_plus_one].
+  # is: [0, $_history_substring_search_number_of_matches_plus_one].  A value
-  # A value of 0 indicates that we are beyond the end of $_history_substring_search_matches.
+  # of 0 indicates that we are beyond the end of
-  # A value of $_history_substring_search_number_of_matches_plus_one indicates that we are beyond
+  # $_history_substring_search_matches.  A value of
-  # the beginning of $_history_substring_search_matches.
+  # $_history_substring_search_number_of_matches_plus_one indicates that we
-
+  # are beyond the beginning of $_history_substring_search_matches.
-  # The initial value of $_history_substring_search_match_number is $_history_substring_search_number_of_matches_plus_one.
+  #
+  # The initial value of $_history_substring_search_match_number is
+  # $_history_substring_search_number_of_matches_plus_one.
+  #
   if [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches_plus_one ]]; then
-
+    #
-    # DOWN was pressed immediately. $_history_substring_search_match_number is still equal to
+    # DOWN was pressed immediately. $_history_substring_search_match_number is
-    # $_history_substring_search_match_number_plus_one. However, there is no highlighting yet:
+    # still equal to $_history_substring_search_match_number_plus_one.
-    # 1) We have to use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND to highlight the current buffer.
+    # However, there is no highlighting yet:
+    #
+    # 1. We have to use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
+    #    to highlight the current buffer.
+    #
     _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
-  elif [[ $_history_substring_search_match_number -le $_history_substring_search_number_of_matches_minus_one ]]; then
 
+  elif [[ $_history_substring_search_match_number -le $_history_substring_search_number_of_matches_minus_one ]]; then
+    #
     # Highlight the next match:
-    # 1) Increase $_history_substring_search_match_number by 1.
+    #
-    # 2) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer.
+    # 1. Increase $_history_substring_search_match_number by 1.
+    #
+    # 2. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+    #    to highlight the current buffer.
+    #
     let "_history_substring_search_match_number = $_history_substring_search_match_number + 1"
     BUFFER=$history[$_history_substring_search_matches[$_history_substring_search_match_number]]
     _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
-  elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches ]]; then
 
+  elif [[ $_history_substring_search_match_number -eq $_history_substring_search_number_of_matches ]]; then
+    #
     # We will move beyond the beginning of $_history_substring_search_matches:
-    # 1) Increase $_history_substring_search_match_number by 1.
+    #
-    # 2) Save the current buffer in $_history_substring_search_old_buffer, so that it can be retrieved by
+    # 1. Increase $_history_substring_search_match_number by 1.
-    #    _history-substring-search-highlight-matches-UP() later.
+    #
-    # 3) Make $BUFFER equal to $_history_substring_search_query.
+    # 2. Save the current buffer in $_history_substring_search_old_buffer,
-    # 4) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND to highlight the current buffer.
+    #    so that it can be retrieved by
+    #    _history-substring-search-highlight-matches-up() later.
+    #
+    # 3. Make $BUFFER equal to $_history_substring_search_query.
+    #
+    # 4. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
+    #    to highlight the current buffer.
+    #
     let "_history_substring_search_match_number = $_history_substring_search_match_number + 1"
     _history_substring_search_old_buffer=$BUFFER
     BUFFER=$_history_substring_search_query
     _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_NOT_FOUND
-  elif [[ $_history_substring_search_match_number -eq 0 ]]; then
 
-    # We were beyond the end of $_history_substring_search_matches but DOWN makes us
+  elif [[ $_history_substring_search_match_number -eq 0 ]]; then
-    # move back to the $_history_substring_search_matches:
+    #
-    # 1) Increase $_history_substring_search_match_number by 1.
+    # We were beyond the end of $_history_substring_search_matches but DOWN
-    # 2) Restore $BUFFER from $_history_substring_search_old_buffer.
+    # makes us move back to the $_history_substring_search_matches:
-    # 3) Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND to highlight the current buffer.
+    #
+    # 1. Increase $_history_substring_search_match_number by 1.
+    #
+    # 2. Restore $BUFFER from $_history_substring_search_old_buffer.
+    #
+    # 3. Use $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
+    #    to highlight the current buffer.
+    #
     let "_history_substring_search_match_number = $_history_substring_search_match_number + 1"
     BUFFER=$_history_substring_search_old_buffer
     _history-substring-search-highlight $HISTORY_SUBSTRING_SEARCH_HIGHLIGHT_FOUND
   fi
+
   _history_substring_search_move_cursor_eol=true
 }
 
@@ -469,7 +553,7 @@ _history-substring-search-end() {
   # zle -R "mn: "$_history_substring_search_match_number" m#: "${#_history_substring_search_matches}
   # read -k -t 200 && zle -U $REPLY
 
-  # Suppress any errors:
+  # Exit successfully from the history-substring-search-* widgets.
   true
 }
 
@@ -485,7 +569,8 @@ history-substring-search-backward() {
   # we only continue if we have NOT entered into up-history:
   if [[ $_history_substring_search_up_history == false ]]; then
 
-    # _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer sets a boolean named
+    # _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer
+    # sets a boolean named
     # $_history_substring_search_check_move_up_within_mutiline_buffer:
     _history-substring-search-check-and-potentially-move-up-within-mutiline-buffer
 
@@ -513,7 +598,8 @@ history-substring-search-forward() {
   # We only continue if we have NOT entered into down-history:
   if [[ $_history_substring_search_down_history == false ]]; then
 
-    # _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer sets a boolean named
+    # _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer
+    # sets a boolean named
     # $_history_substring_search_check_move_down_within_mutiline_buffer:
     _history-substring-search-check-and-potentially-move-down-within-mutiline-buffer