kkoomen · kkoomen · Sep 11, 2019 · Sep 10, 2019 · Sep 11, 2019 · Sep 11, 2019
diff --git a/README.md b/README.md
@@ -37,14 +37,14 @@ on a function, press `<Leader>d`, jump quickly through `TODO` items using
   * [Options](#options)
     + [`g:doge_enable_mappings`](#gdoge_enable_mappings)
     + [`g:doge_mapping`](#gdoge_mapping)
+    + [`g:doge_buffer_mappings`](#gdoge_buffer_mappings)
     + [`g:doge_mapping_comment_jump_forward`](#gdoge_mapping_comment_jump_forward)
     + [`g:doge_mapping_comment_jump_backward`](#gdoge_mapping_comment_jump_backward)
     + [`g:doge_comment_interactive`](#gdoge_comment_interactive)
+    + [`g:doge_comment_jump_wrap`](#gdoge_comment_jump_wrap)
 - [Commands](#commands)
     + [`:DogeGenerate`](#dogegenerate)
 - [Help](#help)
-- [FAQ](#faq)
-    + [Jump-forward trigger requires to be pressed 2 times in order to jump forward](#jump-forward-trigger-requires-to-be-pressed-2-times-in-order-to-jump-forward)
 - [Contributing](#contributing)
 - [Motivation](#motivation)
 - [Supporting DoGe](#supporting-doge)
@@ -144,6 +144,13 @@ Default: `'<Leader>d'`
 
 The mapping to trigger DoGe.
 
+### `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.
+
 ### `g:doge_mapping_comment_jump_forward`
 
 Default: `'<Tab>'`
@@ -164,6 +171,12 @@ Default: `1`
 
 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
 
 ### `:DogeGenerate`
@@ -174,22 +187,6 @@ Command to generate documentation.
 
 To open all the help pages, run `:help doge`.
 
-# FAQ
-
-### Jump-forward trigger requires to be pressed 2 times in order to jump forward
-
-**Problem:**
-This is because you have another plugin that overrides the DoGe default `<Tab>`
-mapping in select mode. UltiSnips could be one of them for most people or any
-other plugin that maps the `<Tab>` character in select mode.
-
-
-**Solution:**
-You can solve this by re-mapping the jump forward/backward keys using
-`g:doge_mapping_comment_jump_forward` and `g:doge_mapping_comment_jump_backward`
-or re-map the other plugins. You can also load DoGe earlier since it uses `nore`
-and thus should prevent other plugins from overwriting at a later stage.
-
 # Contributing
 
 Help or feedback is always appreciated. If you find any bugs, feel free to

diff --git a/autoload/doge/comment.vim b/autoload/doge/comment.vim
@@ -7,6 +7,14 @@ let s:comment_placeholder = doge#helpers#placeholder()
 function! s:jump_forward() abort
   let l:next_pos = search(s:comment_placeholder, 'nW')
 
+  if (l:next_pos > b:doge_interactive['lnum_comment_end_pos'] || l:next_pos == 0)
+    \ && g:doge_comment_jump_wrap == v:true
+    " If we have more TODO items below the comment or we are at the last TODO
+    " inside the comment, then we'll go backward to the start position of the
+    " comment so we can continue to cycle.
+    return "\<Esc>:" . b:doge_interactive['lnum_comment_start_pos'] . "\<CR>^/" . s:comment_placeholder . "\<CR>:silent! noh\<CR>gno\<C-g>"
+  endif
+
   " Check if the next pos we want to jump to is still inside the comment.
   if l:next_pos != 0 && l:next_pos <= b:doge_interactive['lnum_comment_end_pos']
     if mode() ==# 'i'
@@ -30,6 +38,14 @@ endfunction
 function! s:jump_backward() abort
   let l:prev_pos = search(s:comment_placeholder, 'bnW')
 
+  if (l:prev_pos < b:doge_interactive['lnum_comment_start_pos'] || l:prev_pos == 0)
+    \ && g:doge_comment_jump_wrap == v:true
+    " If we have more TODO items above the comment or we are at the first TODO
+    " inside the comment, then we'll go forward to the end position of the
+    " comment so we can continue to cycle.
+    return "\<Esc>:" . b:doge_interactive['lnum_comment_end_pos'] . "\<CR>$?" . s:comment_placeholder . "\<CR>:silent! noh\<CR>gno\<C-g>"
+  endif
+
   " Check if the prev pos we want to jump to is still inside the comment.
   if l:prev_pos != 0 && l:prev_pos >= b:doge_interactive['lnum_comment_start_pos']
     if mode() ==# 'i'

diff --git a/doc/doge.txt b/doc/doge.txt
@@ -57,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*
 

diff --git a/doc/tags b/doc/tags
@@ -22,6 +22,7 @@ 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*
 g:doge_mapping	doge.txt	/*g:doge_mapping*
 g:doge_mapping_comment_jump_backward	doge.txt	/*g:doge_mapping_comment_jump_backward*

diff --git a/plugin/doge.vim b/plugin/doge.vim
@@ -103,6 +103,14 @@ if !exists('g:doge_comment_interactive')
   let g:doge_comment_interactive = 1
 endif
 
+if !exists('g:doge_comment_jump_wrap')
+  ""
+  " (Default: 1)
+  "
+  " Continue to cycle among placeholders when reaching the start or end.
+  let g:doge_comment_jump_wrap = 1
+endif
+
 " Register all the <Plug> mappings.
 nnoremap <Plug>(doge-generate) :call doge#generate()<CR>
 for g:mode in ['n', 'i', 's']

diff --git a/test/options/doge_buffer_mappings.vader b/test/options/doge_buffer_mappings.vader
@@ -20,7 +20,7 @@ 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):
+Expect php (generated comment with a description and @return tag):
   /**
    * Lorem ipsum
    *

diff --git a/test/options/doge_comment_jump_wrap.vader b/test/options/doge_comment_jump_wrap.vader
@@ -0,0 +1,98 @@
+# ==============================================================================
+# Tests the functionality for the g:doge_comment_jump_wrap option.
+# ==============================================================================
+Given php (PHP function without parameters where g:doge_comment_jump_wrap = 1):
+  function myFunction() {}
+
+Do (trigger doge and jump forward):
+  :let g:doge_comment_jump_wrap = 0\<CR>
+  :let g:doge_comment_interactive = 1\<CR>
+  \<C-d>
+  \<Tab>
+  \<Tab>
+
+# Trigger 2 additional <Tab> characters.
+# The cursor should stay on the last TODO item.
+  \<Tab>
+  \<Tab>
+
+Then (the last TODO item should be selected):
+  AssertEqual 4, line('.')
+  AssertEqual 24, col('.')
+
+Expect php (generated comment with a description and @return tag):
+  /**
+   * [TODO:description]
+   *
+   * @return [TODO:type] [TODO:description]
+   */
+  function myFunction() {}
+
+# Jump backwards
+Do (trigger doge and jump backwards):
+  :let g:doge_comment_jump_wrap = 0\<CR>
+  :let g:doge_comment_interactive = 1\<CR>
+  \<C-d>
+# Trigger 2 <S-Tab> characters.
+# The cursor should stay on the first TODO item.
+  \<S-Tab>
+  \<S-Tab>
+
+Then (the first TODO item should be selected):
+  AssertEqual 2, line('.')
+  AssertEqual 4, col('.')
+
+Expect php (generated comment with a description and @return tag):
+  /**
+   * [TODO:description]
+   *
+   * @return [TODO:type] [TODO:description]
+   */
+  function myFunction() {}
+
+# ------------------------------------------------------------------------------
+
+Do (trigger doge and jump forward):
+  :let g:doge_comment_jump_wrap = 1\<CR>
+  :let g:doge_comment_interactive = 1\<CR>
+  \<C-d>
+  \<Tab>
+  \<Tab>
+  \<Tab>
+
+Then (the first TODO item should be selected):
+  AssertEqual 2, line('.')
+  AssertEqual 4, col('.')
+
+Expect php (generated comment with @param and @return tags):
+  /**
+   * [TODO:description]
+   *
+   * @return [TODO:type] [TODO:description]
+   */
+  function myFunction() {}
+
+# Jump backwards
+Do (trigger doge and jump backwards):
+  :let g:doge_comment_jump_wrap = 1\<CR>
+  :let g:doge_comment_interactive = 1\<CR>
+  \<C-d>
+  \<S-Tab>
+  \<S-Tab>
+  \<S-Tab>
+
+Then (the first TODO item should be selected):
+  AssertEqual 2, line('.')
+  AssertEqual 4, col('.')
+
+Expect php (generated comment with @param and @return tags):
+  /**
+   * [TODO:description]
+   *
+   * @return [TODO:type] [TODO:description]
+   */
+  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>
diff --git a/test/vimrc b/test/vimrc
@@ -11,6 +11,9 @@ endif
 " Since the <Leader> key is not an easy way for Vader we'll use <C-d>.
 let g:doge_mapping = '<C-d>'
 
+" Disable the continues comment cyling since this breaks existing tests.
+let g:doge_comment_jump_wrap = 0
+
 " Disable interactive mode in tests, because it will break existing tests and we
 " want to test this manually.
 let g:doge_comment_interactive = 0