Support for synchronous + asynchronous tags file updates (huge refactoring)

See also pull request #49 for my previous and failed attempt:
  https://github.com/xolox/vim-easytags/pull/49

1 files changed, 30 insertions, 36 deletions

diff --git a/doc/easytags.txt b/doc/easytags.txt
index 1e0c037..098b19a 100644
--- a/doc/easytags.txt
+++ b/doc/easytags.txt
@@ -11,15 +11,15 @@ Contents ~
   2. The |:HighlightTags| command
  4. Options                                                  |easytags-options|
   1. The |g:easytags_cmd| option
-  2. The |g:easytags_languages| option
-  3. The |g:easytags_file| option
-  4. The |g:easytags_dynamic_files| option
-  5. The |g:easytags_by_filetype| option
-  6. The |g:easytags_events| option
-  7. The |g:easytags_always_enabled| option
-  8. The |g:easytags_on_cursorhold| option
-  9. The |g:easytags_updatetime_min| option
-  10. The |g:easytags_updatetime_warn| option
+  2. The |g:easytags_async| option
+  3. The |g:easytags_languages| option
+  4. The |g:easytags_file| option
+  5. The |g:easytags_dynamic_files| option
+  6. The |g:easytags_by_filetype| option
+  7. The |g:easytags_events| option
+  8. The |g:easytags_always_enabled| option
+  9. The |g:easytags_on_cursorhold| option
+  10. The |g:easytags_updatetime_min| option
   11. The |g:easytags_auto_update| option
   12. The |g:easytags_auto_highlight| option
   13. The |g:easytags_autorecurse| option
@@ -184,6 +184,22 @@ If you rely entirely on language-specific configuration and don't have a
 general ctags program, set this to the empty string.
 
 -------------------------------------------------------------------------------
+The *g:easytags_async* option
+
+By default vim-easytags runs Exuberant Ctags and updates your tags file in the
+foreground, blocking Vim in the process. As your tags files get larger this
+becomes more annoying. It has been the number one complaint about vim-easytags
+since I published the first release online.
+
+In version 3.5 of the vim-easytags plug-in support for asynchronous tags file
+updates was added. It's not enabled by default yet because I want to make sure
+I'm not breaking the plug-in for the majority of users. However after I've
+gathered some feedback I definitely want to make this the default mode.
+
+By setting this option to true (1) you enable asynchronous tags file updates.
+Good luck! ;-)
+
+-------------------------------------------------------------------------------
 The *g:easytags_languages* option
 
 Exuberant Ctags supports many languages and can be extended via regular
@@ -201,12 +217,9 @@ executable and its arguments must be configured:
   \   }
   \}
 <
-Each key is a special language definition. The key is in the notation of ctags
-in lowercase; you still need to use 'xolox#easytags#map_filetypes()' to map
-this to Vim's filetypes, if necessary.
-
-Above snippets shows the defaults; you only need to specify options that
-differ.
+Each key is a special language definition. The key is a Vim file type in
+lowercase. The above snippet shows the defaults; you only need to specify
+options that differ.
 
 -------------------------------------------------------------------------------
 The *g:easytags_file* option
@@ -322,14 +335,8 @@ Vim's |'updatetime'| option controls how often the easytags plug-in is
 automatically executed. A lot of popular Vim plug-ins manipulate this option to
 control how often they are called. Unfortunately some of those plug-ins set
 |'updatetime'| to a very low value (less than a second) and this can break the
-easytags plug-in.
-
-Because of this the easytags plug-in compensates by keeping track of when it
-was last executed. You'll get one warning when the plug-in first notices a very
-low value of |'updatetime'|, after that the plug-in will shut up (until you
-restart Vim) and simply compensate by not executing until its time has come. If
-you want to silence the warning message forever, see the
-|g:easytags_updatetime_warn| option.
+easytags plug-in. Because of this the easytags plug-in compensates by keeping
+track of when it was last executed.
 
 The default value of Vim's 'updatetime (see |'updatetime'|) option _and_ the
 |g:easytags_updatetime_min| option is 4000 milliseconds (4 seconds).
@@ -344,19 +351,6 @@ easytags plug-in does not support subsecond granularity because it is limited
 by Vim's |localtime()| function which has one-second resolution.
 
 -------------------------------------------------------------------------------
-The *g:easytags_updatetime_warn* option
-
-Since the easytags plug-in now compensates for low |'updatetime'| values (see
-the |g:easytags_updatetime_min| option above) the warning message shown by the
-easytags plug-in has become kind of redundant (and probably annoying?). For now
-it can be completely disabled by setting |g:easytags_updatetime_warn| to 0
-(false).
-
-When the feature that compensates for low |'updatetime'| values has proven to
-be a reliable workaround I will probably remove the warning message and the
-|g:easytags_updatetime_warn| option.
-
--------------------------------------------------------------------------------
 The *g:easytags_auto_update* option
 
 By default the plug-in automatically updates and highlights your tags when you