fix: merge conflict master --> wrap_around

autoload/doge.vim

@@ -5,15 +5,60 @@ set cpoptions&vim
 " @public
 " Generates documentation based on available patterns in b:doge_patterns.
 function! doge#generate() abort
+  let l:success = 0
   if exists('b:doge_patterns')
     for l:pattern in get(b:, 'doge_patterns')
       if doge#generate#pattern(l:pattern) == v:false
         continue
+      else
+        let l:success = v:true
       endif
-      return 1
+      if l:success == v:true
+        call doge#activate()
+      endif
+      return l:success
     endfor
   endif
 endfunction
 
+""
+" @public
+" Activate doge buffer mappings, if option is set.
+function! doge#activate() abort
+  if g:doge_comment_interactive == v:false || g:doge_buffer_mappings == v:false
+    return
+  endif
+
+  let [l:f, l:b] = [
+        \ g:doge_mapping_comment_jump_forward,
+        \ g:doge_mapping_comment_jump_backward,
+        \ ]
+  for l:mode in ['n', 'i', 's']
+    execute(printf('%smap <nowait> <silent> <buffer> %s <Plug>(doge-comment-jump-forward)', l:mode, l:f))
+    execute(printf('%smap <nowait> <silent> <buffer> %s <Plug>(doge-comment-jump-backward)', l:mode, l:b))
+  endfor
+endfunction
+
+""
+" @public
+" Deactivate doge mappings and unlet buffer variable.
+" Can print a message with the reason of deactivation/termination.
+function! doge#deactivate() abort
+  unlet b:doge_interactive
+
+  if g:doge_comment_interactive == v:false || g:doge_buffer_mappings == v:false
+    return
+  endif
+
+  let [l:f, l:b] = [
+        \ g:doge_mapping_comment_jump_forward,
+        \ g:doge_mapping_comment_jump_backward,
+        \ ]
+  for l:mode in ['n', 'i', 's']
+    execute(printf('%sunmap <buffer> %s', l:mode, l:f))
+    execute(printf('%sunmap <buffer> %s', l:mode, l:b))
+  endfor
+endfunction
+
 let &cpoptions = s:save_cpo
 unlet s:save_cpo

autoload/doge/comment.vim

@@ -84,7 +84,7 @@ function! doge#comment#jump(direction) abort
   if exists('b:doge_interactive')
     " Quit interactive mode if the cursor is outside of the comment.
     if line('.') < b:doge_interactive['lnum_comment_start_pos'] || line('.') > b:doge_interactive['lnum_comment_end_pos']
-      unlet b:doge_interactive
+      call doge#deactivate()
       return l:regular_mapping
     endif
 
@@ -105,7 +105,7 @@ function! doge#comment#jump(direction) abort
       endif
     else
       " All the TODO items have been resolved, so we're done.
-      unlet b:doge_interactive
+      call doge#deactivate()
     endif
   endif
 

doc/doge.txt

@@ -34,10 +34,11 @@ Whether or not to enable built-in mappings.
 
 The mapping to trigger DoGe.
 
-                                                    *g:doge_comment_jump_wrap*
+                                                      *g:doge_buffer_mappings*
 (Default: 1)
 
-Continue to cycle among placeholders when reaching the start or end.
+Mappings to jump forward/backward are applied as buffer mappings when
+interactive mode starts, and removed when it ends.
 
                                          *g:doge_mapping_comment_jump_forward*
 (Default: '<Tab>')
@@ -56,6 +57,11 @@ The mapping to jump backward to the previous TODO item in a comment. Requires
 
 Jumps interactively through all TODO items in the generated comment.
 
+                                                    *g:doge_comment_jump_wrap*
+(Default: 1)
+
+Continue to cycle among placeholders when reaching the start or end.
+
 ==============================================================================
 COMMANDS                                                       *doge-commands*
 
@@ -68,6 +74,13 @@ FUNCTIONS                                                     *doge-functions*
 doge#generate()                                              *doge#generate()*
   Generates documentation based on available patterns in b:doge_patterns.
 
+doge#activate()                                              *doge#activate()*
+  Activate doge buffer mappings, if option is set.
+
+doge#deactivate()                                          *doge#deactivate()*
+  Deactivate doge mappings and unlet buffer variable. Can print a message with
+  the reason of deactivation/termination.
+
 doge#comment#jump({direction})                           *doge#comment#jump()*
   Jumps to the previous and next TODO item in the comment based on the
   b:doge_interactive variable. Requires |g:doge_comment_interactive| to be

doc/tags

@@ -1,7 +1,9 @@
 :DogeGenerate	doge.txt	/*:DogeGenerate*
 doge	doge.txt	/*doge*
+doge#activate()	doge.txt	/*doge#activate()*
 doge#comment#jump()	doge.txt	/*doge#comment#jump()*
 doge#comment#update_interactive_comment_info()	doge.txt	/*doge#comment#update_interactive_comment_info()*
+doge#deactivate()	doge.txt	/*doge#deactivate()*
 doge#generate#pattern()	doge.txt	/*doge#generate#pattern()*
 doge#generate()	doge.txt	/*doge#generate()*
 doge#helpers#count()	doge.txt	/*doge#helpers#count()*
@@ -18,6 +20,7 @@ doge-functions	doge.txt	/*doge-functions*
 doge-intro	doge.txt	/*doge-intro*
 doge-preprocessors	doge.txt	/*doge-preprocessors*
 doge.txt	doge.txt	/*doge.txt*
+g:doge_buffer_mappings	doge.txt	/*g:doge_buffer_mappings*
 g:doge_comment_interactive	doge.txt	/*g:doge_comment_interactive*
 g:doge_comment_jump_wrap	doge.txt	/*g:doge_comment_jump_wrap*
 g:doge_enable_mappings	doge.txt	/*g:doge_enable_mappings*

plugin/doge.vim

@@ -5,7 +5,7 @@ let s:unsupported_msg = '[DoGe] Unsupported version. %s is required.'
 
 if !has('nvim') && (v:version < 700 || !has('patch-7.4.2119'))
   echohl WarningMsg
-  echo printf(s:unsupported_msg, 'Vim v7.4.2219+')
+  echo printf(s:unsupported_msg, 'Vim v7.4.2119+')
   echohl None
   finish
 endif
@@ -68,6 +68,15 @@ if !exists('g:doge_mapping')
   let g:doge_mapping = '<Leader>d'
 endif
 
+if !exists('g:doge_buffer_mappings')
+  ""
+  " (Default: 1)
+  "
+  " Mappings to jump forward/backward are applied as buffer mappings when
+  " interactive mode starts, and removed when it ends.
+  let g:doge_buffer_mappings = 1
+endif
+
 if !exists('g:doge_mapping_comment_jump_forward')
   ""
   " (Default: '<Tab>')
@@ -102,22 +111,23 @@ if !exists('g:doge_comment_jump_wrap')
   let g:doge_comment_jump_wrap = 1
 endif
 
+" Register all the <Plug> mappings.
 nnoremap <Plug>(doge-generate) :call doge#generate()<CR>
-nnoremap <expr> <Plug>(doge-comment-jump-forward) doge#comment#jump('forward')
-nnoremap <expr> <Plug>(doge-comment-jump-backward) doge#comment#jump('backward')
-inoremap <expr> <Plug>(doge-comment-jump-forward) doge#comment#jump('forward')
-inoremap <expr> <Plug>(doge-comment-jump-backward) doge#comment#jump('backward')
-snoremap <expr> <Plug>(doge-comment-jump-forward) doge#comment#jump('forward')
-snoremap <expr> <Plug>(doge-comment-jump-backward) doge#comment#jump('backward')
+for g:mode in ['n', 'i', 's']
+  execute(printf('%snoremap <expr> <Plug>(doge-comment-jump-forward) doge#comment#jump("forward")', g:mode))
+  execute(printf('%snoremap <expr> <Plug>(doge-comment-jump-backward) doge#comment#jump("backward")', g:mode))
+endfor
+unlet g:mode
 
 if g:doge_enable_mappings == v:true
   execute(printf('nmap <silent> %s <Plug>(doge-generate)', g:doge_mapping))
-  execute(printf('nmap <silent> %s <Plug>(doge-comment-jump-forward)', g:doge_mapping_comment_jump_forward))
-  execute(printf('nmap <silent> %s <Plug>(doge-comment-jump-backward)', g:doge_mapping_comment_jump_backward))
-  execute(printf('imap <silent> %s <Plug>(doge-comment-jump-forward)', g:doge_mapping_comment_jump_forward))
-  execute(printf('imap <silent> %s <Plug>(doge-comment-jump-backward)', g:doge_mapping_comment_jump_backward))
-  execute(printf('smap <silent> %s <Plug>(doge-comment-jump-forward)', g:doge_mapping_comment_jump_forward))
-  execute(printf('smap <silent> %s <Plug>(doge-comment-jump-backward)', g:doge_mapping_comment_jump_backward))
+  if g:doge_buffer_mappings == v:false
+    for g:mode in ['n', 'i', 's']
+      execute(printf('%smap <silent> %s <Plug>(doge-comment-jump-forward)', g:mode, g:doge_mapping_comment_jump_forward))
+      execute(printf('%smap <silent> %s <Plug>(doge-comment-jump-backward)', g:mode, g:doge_mapping_comment_jump_backward))
+    endfor
+    unlet g:mode
+  endif
 endif
 
 ""

test/options/doge_buffer_mappings.vader

@@ -0,0 +1,33 @@
+# ==============================================================================
+# Tests the functionality for the g:doge_buffer_mappings option.
+# ==============================================================================
+Given php (PHP function without parameters where g:doge_buffer_mappings = 1):
+  function myFunction() {}
+
+Do (trigger doge):
+  :let g:doge_comment_interactive = 1\<CR>
+  \<C-d>
+  Lorem ipsum
+  \<Tab>
+  void
+  \<Tab>
+  Lorem ipsum
+
+# Trigger an additional <Tab> to deactivate DoGe.
+  \<Tab>
+
+Then (all buffer mappings should not exists anymore):
+  AssertEqual 0, hasmapto('<Plug>(doge-comment-jump-forward)', 'nis')
+  AssertEqual 0, hasmapto('<Plug>(doge-comment-jump-backward)', 'nis')
+
+Expect php (generated comment with @param and @return tags):
+  /**
+   * Lorem ipsum
+   *
+   * @return void Lorem ipsum 
+   */
+  function myFunction() {}
+
+Do (let g:doge_comment_interactive = 0):
+# Disable the option again so that upcoming tests will not fail.
+  :let g:doge_comment_interactive = 0\<CR>

test/options/doge_comment_interactive.vader

@@ -1,8 +1,5 @@
 # ==============================================================================
 # Tests the functionality for the g:doge_comment_interactive option.
-#
-# We test PHP because we will test the functionality of a commment being
-# inserted above.
 # ==============================================================================
 Given php (PHP function with parameters where g:doge_comment_interactive = 0):
   function myFunction(array &$p1, string $p2, &$p3 = NULL, \Drupal\core\Entity\Node $p4) {}
@@ -183,4 +180,5 @@ Expect python (generated comment with :param tags with brief descriptions):
       pass
 
 Do (let g:doge_comment_interactive = 0):
+# Disable the option again so that upcoming tests will not fail.
   :let g:doge_comment_interactive = 0\<CR>