Add comments to document the code

Also add some FIXME markers in places where the code needs more
explanation.

autoload/vundle/installer.vim

@@ -1,3 +1,9 @@
+" Try to clone all new bundles given (or all bundles in g:bundles by default)
+" to g:bundle_dir.  If a:bang is 1 it will also update all plugins (git pull).
+"
+" bang   -- 1 or 0
+" ...    -- any number of bundle specifications (seperate arguments)
+" return -- 0 (unconditionally)
 func! vundle#installer#new(bang, ...) abort
   let bundles = (a:1 == '') ?
         \ g:bundles :
@@ -6,12 +12,22 @@ func! vundle#installer#new(bang, ...) abort
   let names = vundle#scripts#bundle_names(map(copy(bundles), 'v:val.name_spec'))
   call vundle#scripts#view('Installer',['" Installing plugins to '.expand(g:bundle_dir, 1)], names +  ['Helptags'])
 
+  " FIXME this tries to call 'add' as a normal mode command.  This is a buffer
+  " local mapping defined in vundle#scripts#view().  The mapping will call a
+  " buffer local command InstallPlugin which in turn will call
+  " vundle#installer#run() with vundle#installer#install().  This is very
+  " confusing and unclear.
   call s:process(a:bang, (a:bang ? 'add!' : 'add'))
 
   call vundle#config#require(bundles)
 endf
 
-
+" Iterate over all lines in a Vundle window and execute the given command for
+" every line.  Used by the installation and cleaning functions.
+"
+" bang   -- not used (FIXME)
+" cmd    -- the (normal mode) command to execute for every line as a string
+" return -- 0 (unconditionally)
 func! s:process(bang, cmd)
   let msg = ''
 
@@ -43,6 +59,13 @@ func! s:process(bang, cmd)
   echo 'Done! '.msg
 endf
 
+" Call another function in the different Vundle windows.
+"
+" func_name -- the function to call
+" name      -- the bundle name to call func_name for (string)
+" ...       -- the argument to be used when calling func_name (only the first
+"              optional argument will be used)
+" return    -- the status returned by the call to func_name
 func! vundle#installer#run(func_name, name, ...) abort
   let n = a:name
 
@@ -83,6 +106,11 @@ func! vundle#installer#run(func_name, name, ...) abort
   return status
 endf
 
+" Put a sign on the current line, indicating the status of the installation
+" step.
+"
+" status -- string describing the status
+" return -- 0 (unconditionally)
 func! s:sign(status)
   if (!has('signs'))
     return
@@ -91,6 +119,11 @@ func! s:sign(status)
   exe ":sign place ".line('.')." line=".line('.')." name=Vu_". a:status ." buffer=" . bufnr("%")
 endf
 
+" Install a plugin, then add it to the runtimepath and source it.
+"
+" bang   -- 1 or 0, passed directly to vundle#installer#install()
+" name   -- the name of a bundle (string)
+" return -- the return value from vundle#installer#install()
 func! vundle#installer#install_and_require(bang, name) abort
   let result = vundle#installer#install(a:bang, a:name)
   let b = vundle#config#bundle(a:name, {})
@@ -99,6 +132,11 @@ func! vundle#installer#install_and_require(bang, name) abort
   return result
 endf
 
+" Install or update a bundle given by its name.
+"
+" bang   -- 1 or 0, passed directly to s:sync()
+" name   -- the name of a bundle (string)
+" return -- the return value from s:sync()
 func! vundle#installer#install(bang, name) abort
   if !isdirectory(g:bundle_dir) | call mkdir(g:bundle_dir, 'p') | endif
 
@@ -114,6 +152,9 @@ func! vundle#installer#install(bang, name) abort
   return s:sync(a:bang, b)
 endf
 
+" Call :helptags for all bundles in g:bundles.
+"
+" return -- 'error' if an error occurred, else return 'helptags'
 func! vundle#installer#docs() abort
   let error_count = vundle#installer#helptags(g:bundles)
   if error_count > 0
@@ -122,6 +163,11 @@ func! vundle#installer#docs() abort
   return 'helptags'
 endf
 
+" Call :helptags for a list of bundles.
+"
+" bundles -- a list of bundle dictionaries for which :helptags should be
+"            called.
+" return  -- the number of directories where :helptags failed
 func! vundle#installer#helptags(bundles) abort
   let bundle_dirs = map(copy(a:bundles),'v:val.rtpath')
   let help_dirs = filter(bundle_dirs, 's:has_doc(v:val)')
@@ -137,6 +183,11 @@ func! vundle#installer#helptags(bundles) abort
   return len(errors)
 endf
 
+" List all installed plugins.
+" Corresponding documentation: vundle-plugins-list
+"
+" bang   -- not used
+" return -- 0 (unconditionally)
 func! vundle#installer#list(bang) abort
   let bundles = vundle#scripts#bundle_names(map(copy(g:bundles), 'v:val.name_spec'))
   call vundle#scripts#view('list', ['" My Plugins'], bundles)
@@ -144,7 +195,12 @@ func! vundle#installer#list(bang) abort
   echo len(g:bundles).' plugins configured'
 endf
 
-
+" List and remove all directories in the bundle directory which are not
+" activated (added to the bundle list).
+"
+" bang   -- 0 if the user should be asked to confirm every deletion, 1 if they
+"           should be removed unconditionally
+" return -- 0 (unconditionally)
 func! vundle#installer#clean(bang) abort
   let bundle_dirs = map(copy(g:bundles), 'v:val.path()')
   let all_dirs = (v:version > 702 || (v:version == 702 && has("patch51")))
@@ -175,7 +231,12 @@ func! vundle#installer#clean(bang) abort
   endif
 endf
 
-
+" Delete to directory for a plugin.
+"
+" bang     -- not used
+" dir_name -- the bundle directory to be deleted (as a string)
+" return   -- 'error' if an error occurred, 'deleted' if the plugin folder was
+"             successfully deleted
 func! vundle#installer#delete(bang, dir_name) abort
 
   let cmd = ((has('win32') || has('win64')) && empty(matchstr(&shell, 'sh'))) ?
@@ -199,6 +260,10 @@ func! vundle#installer#delete(bang, dir_name) abort
   endif
 endf
 
+" Check if a bundled plugin has any documentation.
+"
+" rtp    -- a path (string) where the plugin is installed
+" return -- 1 if some documentation was found, 0 otherwise
 func! s:has_doc(rtp) abort
   return isdirectory(a:rtp.'/doc')
   \   && (!filereadable(a:rtp.'/doc/tags') || filewritable(a:rtp.'/doc/tags'))
@@ -207,6 +272,10 @@ func! s:has_doc(rtp) abort
   \     : !(empty(glob(a:rtp.'/doc/*.txt')) && empty(glob(a:rtp.'/doc/*.??x')))
 endf
 
+" Update the helptags for a plugin.
+"
+" rtp    -- the path to the plugin's root directory (string)
+" return -- 1 if :helptags succeeded, 0 otherwise
 func! s:helptags(rtp) abort
   " it is important to keep trailing slash here
   let doc_path = resolve(a:rtp . '/doc/')
@@ -220,6 +289,15 @@ func! s:helptags(rtp) abort
   return 1
 endf
 
+" Install or update a given bundle object with git.
+"
+" bang   -- 0 if only new plugins should be installed, 1 if existing plugins
+"           should be updated
+" bundle -- a bundle object (dict)
+" return -- 'todate' if nothing was updated or the repository was up to date,
+"           'new' when the plugin was newly installed, 'updated' if some
+"           changes where pulled via git, 'error' if an error occurred in the
+"           shell command
 func! s:sync(bang, bundle) abort
   " Do not sync if this bundle is pinned
   if a:bundle.is_pinned()
@@ -265,6 +343,11 @@ func! s:sync(bang, bundle) abort
   return 'updated'
 endf
 
+" Escape special characters in a string to be able to use it as a shell
+" command with system().
+"
+" cmd    -- the string holding the shell command
+" return -- a string with the relevant characters escaped
 func! vundle#installer#shellesc(cmd) abort
   if ((has('win32') || has('win64')) && empty(matchstr(&shell, 'sh')))
     return '"' . substitute(a:cmd, '"', '\\"', 'g') . '"'
@@ -272,6 +355,10 @@ func! vundle#installer#shellesc(cmd) abort
   return shellescape(a:cmd)
 endf
 
+" Fix a cd shell command to be used on Windows.
+"
+" cmd    -- the command to be fixed (string)
+" return -- the fixed command (string)
 func! g:shellesc_cd(cmd) abort
   if ((has('win32') || has('win64')) && empty(matchstr(&shell, 'sh')))
     let cmd = substitute(a:cmd, '^cd ','cd /d ','')  " add /d switch to change drives
@@ -281,10 +368,21 @@ func! g:shellesc_cd(cmd) abort
   endif
 endf
 
+" Make a system call.  This can be used to change the way system calls
+" are made during developing, without searching the whole code base for
+" actual system() calls.
+"
+" cmd    -- the command passed to system() (string)
+" return -- the return value from system()
 func! s:system(cmd) abort
   return system(a:cmd)
 endf
 
+" Add a log message to Vundle's internal logging variable.
+"
+" str    -- the log message (string)
+" prefix -- optional prefix for multiline entries (string)
+" return -- a:str
 func! s:log(str, ...) abort
   let prefix = a:0 > 0 ? a:1 : ''
   let fmt = '%Y-%m-%d %H:%M:%S'