Add JumpToNearbyTag functionality (#780)

* Add JumpToNearbyTag functionality

Closes #779

Updated functions:

`s:GetNearbyTag()` - Allow for a direction parameter to be passed into
the routine. This will allow for a forward or backward search. It will
default to a backward search line the current behavior if the
`a:direction` parameter is not used.

`s:JumpToTag()` - Allow for an optional parameter to be passed in to
specify the tag instead of using the tag under the cursor on the current
line. This also allows this routine to be executed from the file window
instead of the tagbar window. Assume `autoclose=0` if passing in the tag.

Add new functions:

`s:JumpToNearbyTag()` - This routine will do a forward or backward search
for the nearst tag using the `GetNearbyTag()` with the new direction
field, then call the `JumpToTag()` with the tag we found.

`tagbar#jumpToNextTag()` - New public facing wrapper routine around the
`JumpToNearbyTag()` routine. Optionally take in `a:lnum` and
`a:search_method` to be used in other routines. If `a:lnum` is not
present, then the line number will search from the next or previous line
depending on the `a:direction` value.

TODO:
- [ ] Still need to write up the documentation for this.
- [ ] Possibly look at providing default keymap. Currently this can be
  done using a custom definition in `.vimrc`.

* Add documentation and fix lazy scroll

Added documentation for this feature
Corrected the lazy scroll behavior when the next/prev tag is visible
Use the existing `w:autoclose` if set, else default to 0.

* Fix argument ordering

Correct the argument ordering and numbering for the jumpToNearbyTag()
routine.
Add documentation example for the 'nearest' search-method.
Rename jumpToNextTag() to jumpToNearbyTag() to be more inline with the
other routines.

* remove debug

* Fix current line processing

In the event there is a tag on the immediately previous/next line, then
the GetNearbyTag will return that tag even if the scoped-stl
search-method is set.

* Cleanup optional argument initialization

* Update tagbar#jumpToNearbyTag() - remove lnum and add flags parameter

Changes to the tagbar#jumpToNearbyTag() routine to allow more
flexibility. Removing the optional lnum parameter as this likely will
not be needed and could actually cause confusion in its use. Add a flags
field so different options can be set such as the 's':'scroll_offset'
option.

doc/tagbar.txt

@@ -329,6 +329,20 @@ COMMANDS                                                     *tagbar-commands*
 
     This command will call the |tagbar#jump()| function.
 
+:TagbarJumpPrev                                             *:TagbarJumpPrev*
+    Jump to the previous tag under the cursor. This works in the file window.
+    This will search for the previous {'nearest-stl'} type tag starting at the
+    line just before the current line and do a backwards search.
+
+    This command will call the |tagbar#jumpToNearbyTag(-1)| function.
+
+:TagbarJumpNext                                             *:TagbarJumpNext*
+    Jump to the next tag under the cursor. This works in the file window.
+    This will search for the next {'nearest-stl'} type tag starting at the
+    line just after the current line and do a forward search.
+
+    This command will call the |tagbar#jumpToNearbyTag(1)| function.
+
 ------------------------------------------------------------------------------
 FUNCTIONS                                                   *tagbar-functions*
 
@@ -378,6 +392,45 @@ FUNCTIONS                                                   *tagbar-functions*
 
     This is the function called when using the |:TagbarJump| command.
 
+*tagbar#jumpToNearbyTag()*
+    This function will jump to the next tag or previous tag starting a search
+    from the line under the cursor. This works when in the file window instead
+    of inside the tagbar window like the |tagbar#jump()| function.
+
+    The direction of search must be provided. If the [direction] is greater
+    than 0, then it will do a forward search. If the [direction] is less
+    than 0, then it will do a backward search.
+
+    Can also optionally provide a [search_method] which is used in the
+    |tagbar#GetTagNearLine()| function call and behaves the same way. This
+    will default to *'nearest-stl'* if not specified.
+
+    Can optionally provide a flags field [flags] to control the nearby tag
+    jumping. The flags should be a string of characters with the following
+    meanings:
+        's' - use the |g:tagbar_scroll_off| setting when jumping
+
+    Full syntax:
+        tagbar#jumpToNearbyTag(direction [, {search-method} [, {flags}]])
+
+    Examples:
+>
+    " These keymaps will jump to the next/prev tag that can be scoped. Ex:
+    " function calls, class definitions, etc.
+    nnoremap t] :call tagbar#jumpToNearbyTag(1)
+    nnoremap t[ :call tagbar#jumpToNearbyTag(-1)
+
+    " These keymaps will jump to the next/prev tag regardless of type. Ex:
+    " function calls, class definitions, variable definitions, typedefs, etc.
+    nnoremap t] :call tagbar#jumpToNearbyTag(1, 'nearest')
+    nnoremap t[ :call tagbar#jumpToNearbyTag(-1, 'nearest')
+
+    " These keymaps will jump to the next/prev tag regardless of type, and
+    " will also use the jump_offset configuration to position the cursor
+    nnoremap t] :call tagbar#jumpToNearbyTag(1, 'nearest', 's')
+    nnoremap t[ :call tagbar#jumpToNearbyTag(-1, 'nearest', 's')
+<
+
 ------------------------------------------------------------------------------
 KEY MAPPINGS                                                     *tagbar-keys*