From 9ca1c72bbd022e366c59e2800e33780a6a7fff1a Mon Sep 17 00:00:00 2001
From: Tom Ryder <tom@sanctum.geek.nz>
Date: Wed, 8 Aug 2018 13:46:29 +1200
Subject: Add and revise some comments

---
 vim/after/ftplugin/mail.vim | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

(limited to 'vim/after')

diff --git a/vim/after/ftplugin/mail.vim b/vim/after/ftplugin/mail.vim
index b10a79ab..0082ea78 100644
--- a/vim/after/ftplugin/mail.vim
+++ b/vim/after/ftplugin/mail.vim
@@ -62,27 +62,49 @@ nnoremap <buffer>
       \ <C-U>:call <SID>FlagUnimportant()<CR>
 let b:undo_ftplugin .= '|nunmap <buffer> <LocalLeader>l'
 
-" Maps to move to the next blank line content-wise (i.e. quoted still counts)
+" Move through quoted paragraphs like normal-mode `{` and `}`
 function! s:NewBlank(start, count, up) abort
+
+  " Flag for whether we've started a block
   let l:block = 0
+
+  " Flag for the number of blocks passed
   let l:blocks = 0
+
+  " Iterate through buffer lines
   let l:num = a:start
   while l:num > 0 && l:num <= line('$')
+
+    " If the line is blank
     if getline(l:num) =~# '^[ >]*$'
+
+      " If we'd moved through a non-blank block already, reset that flag and
+      " bump up the block count
       if l:block
         let l:block = 0
         let l:blocks += 1
       endif
+
+      " If we've hit the number of blocks, end the loop
       if l:blocks == a:count
         break
       endif
+
+    " If the line is not blank, flag that we're going through a block
     else
       let l:block = 1
     endif
+
+    " Move the line number or up or down depending on direction
     let l:num += a:up ? -1 : 1
   endwhile
+
+  " Move to line (needs jumps and marks setting)
   execute l:num
+
 endfunction
+
+" Maps using NewBlank() function above for quoted paragraph movement
 nnoremap <buffer> <silent> <LocalLeader>[
       \ :<C-U>call <SID>NewBlank(line('.'), v:count1, 1)<CR>
 nnoremap <buffer> <silent> <LocalLeader>]
-- 
cgit v1.2.3