Add option for g:tagbar_highlight_method (#709)

* Add option for g:tagbar_highlight_current_tag

Closes #708

Add option for g:tagbar_highlight_current_tag which will allow
highlighting of tags on the current line in addition to highlighting the
scoped tags. Reverts the behavior added in #638 to the default from
before that commit

* Rework to allow direct configuration of highlight method

* Address review comments

autoload/tagbar.vim

@@ -2186,9 +2186,9 @@ function! s:HighlightTag(openfolds, ...) abort
     let force = a:0 > 0 ? a:1 : 0
 
     if a:0 > 1
-        let tag = s:GetNearbyTag('nearest-stl', 0, a:2)
+        let tag = s:GetNearbyTag(g:tagbar_highlight_method, 0, a:2)
     else
-        let tag = s:GetNearbyTag('nearest-stl', 0)
+        let tag = s:GetNearbyTag(g:tagbar_highlight_method, 0)
     endif
     if !empty(tag)
         let tagline = tag.tline
@@ -3111,8 +3111,7 @@ function! s:GetNearbyTag(request, forcecurrent, ...) abort
     for line in range(curline, 1, -1)
         if has_key(fileinfo.fline, line)
             let curtag = fileinfo.fline[line]
-            if a:request ==# 'nearest-stl'
-                        \ && typeinfo.getKind(curtag.fields.kind).stl || line == curline
+            if a:request ==# 'nearest-stl' && typeinfo.getKind(curtag.fields.kind).stl
                 let tag = curtag
                 break
             elseif a:request ==# 'scoped-stl'
@@ -3121,7 +3120,7 @@ function! s:GetNearbyTag(request, forcecurrent, ...) abort
                         \ && curline <= curtag.fields.end
                 let tag = curtag
                 break
-            elseif a:request ==# 'nearest'
+            elseif a:request ==# 'nearest' || line == curline
                 let tag = curtag
                 break
             endif

doc/tagbar.txt

@@ -1090,6 +1090,53 @@ containing the tag without scrolling the window.  If the tag is not visible
 in the window then the window will be scrolled and the tag (and cursor)
 placed in the location dictated by |g:tagbar_jump_offset|.
 
+                                                  *g:tagbar_highlight_method*
+g:tagbar_highlight_method~
+Default: 'nearest-stl'
+
+This configuration controls how the tag highlighting works in the tagbar
+window. The possible values are:
+    'nearest-stl'    - Highlight the nearest tag that is defined with the
+                       {stl} option
+    'scoped-stl'     - Highlight the nearest tag defined with the {stl} flag
+                       in the kind definition, also taking into account the
+                       scope.
+    'nearest'        - Highlight the nearest tag regardless of the type or
+                       flags. This was the behavior prior to the introduction
+                       of the 'scoped-stl' idea. If you want to revert to the
+                       old method, set |g:tagbar_highlight_method| to
+                       'nearest'.
+
+Use case example: Consider the following example. If the cursor is at line
+#10, then the highlight method will behave differently in each case. If set to
+'nearest-stl', the tag for some_function() will be highlighted. If set to
+'scoped-stl', the tag for 'class A' will be highlighted. If set to 'nearest',
+then the tag for 'SOME_MACRO' will be highlighted.
+
+If the cursor is moded to line #8, then both 'nearest-stl' and 'scoped-stl'
+will highlight the tag for 'some_function()'. The 'nearest' method will
+highlight the 'SOME_MACRO' tag.
+>
+        1  class A {
+        2
+        3      int some_function(int arg) {
+        4          int var1;
+        5          int var2;
+        6  #define SOME_MACRO 1
+        7          ...
+        8          printf("...");
+        9      }
+        10
+        11     int another_function(int arg) {
+        12         int varA;
+        13         printf("###");
+        14     }
+        15 }
+<
+Example: >
+        let g:tagbar_highlight_method = 'nearest'
+<
+
 ------------------------------------------------------------------------------
 HIGHLIGHT COLOURS                                           *tagbar-highlight*
 

plugin/tagbar.vim

@@ -100,6 +100,7 @@ function! s:setup_options() abort
         \ ['jump_lazy_scroll', 0],
         \ ['left', 0],
         \ ['help_visibility', 0],
+        \ ['highlight_method', 'nearest-stl'],
         \ ['position', default_pos],
         \ ['previewwin_pos', previewwin_pos],
         \ ['scopestrs', {}],