Add a few comment lines

9 files changed, 49 insertions, 0 deletions

diff --git a/vim/autoload/colorscheme.vim b/vim/autoload/colorscheme.vim
index db965d99..349ee374 100644
--- a/vim/autoload/colorscheme.vim
+++ b/vim/autoload/colorscheme.vim
@@ -9,6 +9,7 @@ function! colorscheme#UpdateCursorline(colors_name, list) abort
   " on if the current colorscheme is in the whitelist, and off otherwise; fire
   " the WinEnter and WinLeave events so any other 'cursorline' related hooks
   " can run too
+  "
   let l:cursorline = index(a:list, a:colors_name) >= 0
   tabdo windo let &g:cursorline = l:cursorline
         \| silent doautocmd WinEnter,WinLeave
diff --git a/vim/autoload/escape.vim b/vim/autoload/escape.vim
index 0fdfba99..37ac3e8b 100644
--- a/vim/autoload/escape.vim
+++ b/vim/autoload/escape.vim
@@ -1,13 +1,18 @@
+" Escape text for use as an Ex command argument
 function! escape#Arg(arg) abort
   return exists('*fnameescape')
         \ ? fnameescape(a:arg)
         \ : escape(a:arg, "\n\r\t".' *?[{`$\%#''"|!<')
 endfunction
 
+" Escape text for use as a list item
 function! escape#Item(item) abort
   return escape(a:item, ',')
 endfunction
 
+" Escape wildcard characters in list items to prevent e.g. tilde or glob
+" expansion in the resulting item
+"
 function! escape#Wild(string) abort
   return escape(a:string, '\*?[{`''$~')
 endfunction
diff --git a/vim/autoload/fortune.vim b/vim/autoload/fortune.vim
index 6bbe6b3b..da6e2fa3 100644
--- a/vim/autoload/fortune.vim
+++ b/vim/autoload/fortune.vim
@@ -1,23 +1,32 @@
+" Declare paths to check for fortune files
 let s:paths = [
       \ $HOME.'/.fortunes',
       \ $HOME.'/.local/share/games/fortunes',
       \]
 
+" List of executables for which we need to check
 let s:executables = [
       \ 'fortune',
       \ 'timeout',
       \]
 
+" Entry point for plugin
 function! fortune#() abort
 
+  " Check we have all of the executables we need
   for executable in s:executables
     if !executable(executable)
       echoerr 'Missing executable "'.executable.'"'
     endif
   endfor
 
+  " Maximum length of fortunes is the width of the screen minus 1; characters
+  " wider than one column will break this
+  "
   let limit = &columns - 1
 
+  " Some implementations of fortune(6) thrash the disk if they can't meet the
+  " length limit, so we need to rap this invocation in a timeout(1) call
   let command = [
         \ 'timeout',
         \ '0.3s',
@@ -27,6 +36,7 @@ function! fortune#() abort
         \ limit,
         \]
 
+  " Find a path for custom fortunes and add it on to the command if found
   for path in s:paths
     if isdirectory(path)
       call add(command, path)
@@ -34,6 +44,8 @@ function! fortune#() abort
     endif
   endfor
 
+  " Run the command and condense any control or space character groups into
+  " just one space
   let fortune = substitute(
         \ system(join(command)),
         \ '[[:cntrl:][:space:]]\+',
@@ -41,6 +53,7 @@ function! fortune#() abort
         \ 'g',
         \)
 
+  " Show the fortune message!
   echomsg fortune
 
 endfunction
diff --git a/vim/autoload/gitcommit.vim b/vim/autoload/gitcommit.vim
index 7aba1c5b..72d2b9ff 100644
--- a/vim/autoload/gitcommit.vim
+++ b/vim/autoload/gitcommit.vim
@@ -3,6 +3,7 @@ function! gitcommit#CursorColumn() abort
 
   " If we can find a line after the first that isn't a comment, we're
   " composing the message
+  "
   for num in range(1, line('$'))
     if num == 1
       continue
diff --git a/vim/autoload/has.vim b/vim/autoload/has.vim
index 0100e913..c67420a5 100644
--- a/vim/autoload/has.vim
+++ b/vim/autoload/has.vim
@@ -1,7 +1,20 @@
+" Wrapper to backport the nicer has() syntax for simultaneous version and
+" patch level checking that was introduced in v7.4.236 and fixed in v7.4.237.
+"
+" * <https://github.com/vim/vim/releases/tag/v7.4.236>
+" * <https://github.com/vim/vim/releases/tag/v7.4.237>
+"
 function! has#(feature) abort
+
+  " If we're new enough, we can just run the native has()
   if has('patch-7.4.237')
     return has(a:feature)
   endif
+
+  " Otherwise, we have to break down the pattern and do manual version and
+  " patch level checks; if it doesn't match the patch syntax, just return what
+  " the native has() does
+  "
   let feature = a:feature
   let pattern = 'patch-\(\d\+\)\.\(\d\+\)\.\(\d\+\)'
   let matchlist = matchlist(feature, pattern)
@@ -9,8 +22,13 @@ function! has#(feature) abort
     return has(a:feature)
   endif
   let [major, minor, patch] = matchlist[1:3]
+
+  " The v:version variable looks like e.g. 801 for v8.1
   let l:version = major * 100 + minor
+
+  " Compare the version numbers, and then the patch level if they're the same
   return v:version != l:version
         \ ? v:version > l:version
         \ : has('patch-'.patch)
+
 endfunction
diff --git a/vim/autoload/markdown.vim b/vim/autoload/markdown.vim
index 8bac8045..6c8187a0 100644
--- a/vim/autoload/markdown.vim
+++ b/vim/autoload/markdown.vim
@@ -9,10 +9,12 @@ function! markdown#Heading(char) abort
 
   " Build underline string by repeating character by the string length of the
   " heading text
+  "
   let underline = repeat(a:char, strlen(heading))
 
   " If the line after this one looks like it's already an underline, replace
   " it; otherwise, create a new underline
+  "
   if getline(pos[1] + 1) =~# '^[-=]\{2,}$'
     call setline(pos[1] + 1, underline)
   else
diff --git a/vim/autoload/plugin.vim b/vim/autoload/plugin.vim
index 68e3d54b..629a4367 100644
--- a/vim/autoload/plugin.vim
+++ b/vim/autoload/plugin.vim
@@ -1,3 +1,6 @@
+" Check whether plugins are enabled and a specific named plugin (excluding
+" extension .vim) is available somewhere within 'runtimepath'
+"
 function! plugin#Ready(name) abort
   return &loadplugins
         \ && globpath(&runtimepath, 'plugin/'.a:name.'.vim') !=# ''
diff --git a/vim/autoload/reload.vim b/vim/autoload/reload.vim
index 558f24d6..322c44d2 100644
--- a/vim/autoload/reload.vim
+++ b/vim/autoload/reload.vim
@@ -1,9 +1,13 @@
+" Re-run filetype detection, if it's run before
 function! reload#FileType() abort
   if exists('g:did_load_filetypes')
     doautocmd filetypedetect BufRead
   endif
 endfunction
 
+" Re-read .vimrc file, reloading filetypes afterwards to avoid masking
+" filetype plugin settings
+"
 function! reload#Vimrc() abort
   noautocmd source $MYVIMRC
   call reload#FileType()
diff --git a/vim/autoload/unescape.vim b/vim/autoload/unescape.vim
index a809827d..d42403f8 100644
--- a/vim/autoload/unescape.vim
+++ b/vim/autoload/unescape.vim
@@ -1,3 +1,5 @@
+" Unescape a list item escaped with escape#Item(), by replacing all escaped
+" commas with unescaped ones
 function! unescape#Item(key, val) abort
   return substitute(a:val, '\\,', ',', 'g')
 endfunction