Add comments to document the code

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

autoload/vundle/config.vim

@@ -1,3 +1,8 @@
+" Add a plugin to the runtimepath.
+"
+" arg    -- a string specifying the plugin
+" ...    -- a dictionary of options for the plugin
+" return -- the return value from vundle#config#init_bundle()
 func! vundle#config#bundle(arg, ...)
   let bundle = vundle#config#init_bundle(a:arg, a:000)
   if exists('g:vundle_lazy_load') && g:vundle_lazy_load
@@ -16,12 +21,19 @@ func! vundle#config#activate_bundles()
   call s:rtp_add_defaults()
 endf
 
+" Initialize Vundle.
+"
+" return -- 0 (unconditionally)
 func! vundle#config#init()
   if !exists('g:bundles') | let g:bundles = [] | endif
   call s:rtp_rm_a()
   let g:bundles = []
 endf
 
+" Add a list of bundles to the runtimepath and source them.
+"
+" bundles -- a list of bundle objects
+" return  -- 0 (unconditionally)
 func! vundle#config#require(bundles) abort
   for b in a:bundles
     call s:rtp_add(b.rtpath)
@@ -34,6 +46,11 @@ func! vundle#config#require(bundles) abort
   call s:rtp_add_defaults()
 endf
 
+" Create a bundle object from a bundle specification.
+"
+" name   -- the bundle specification as a string
+" opts   -- the options dictionary from then bundle definition
+" return -- an initialized bundle object
 func! vundle#config#init_bundle(name, opts)
   if a:name != substitute(a:name, '^\s*\(.\{-}\)\s*$', '\1', '')
     echo "Spurious leading and/or trailing whitespace found in plugin spec '" . a:name . "'"
@@ -44,6 +61,12 @@ func! vundle#config#init_bundle(name, opts)
   return b
 endf
 
+" Parse the options which can be supplied with the bundle specification.
+" Corresponding documentation: vundle-plugins-configure
+"
+" opts   -- a dictionary with the user supplied options for the bundle
+" return -- a dictionary with the user supplied options for the bundle, this
+"           will be merged with a s:bundle object into one dictionary.
 func! s:parse_options(opts)
   " TODO: improve this
   if len(a:opts) != 1 | return {} | endif
@@ -55,6 +78,13 @@ func! s:parse_options(opts)
   endif
 endf
 
+" Parse the plugin specification.  Corresponding documentation:
+" vundle-plugins-uris
+"
+" arg    -- the string supplied to identify the plugin
+" return -- a dictionary with the folder name (key 'name') and the uri (key
+"           'uri') for cloning the plugin  and the original argument (key
+"           'name_spec')
 func! s:parse_name(arg)
   let arg = a:arg
   let git_proto = exists('g:vundle_default_git_proto') ? g:vundle_default_git_proto : 'https'
@@ -94,6 +124,10 @@ func! s:rtp_add_defaults()
 endf
 
 
+" Remove all paths for the plugins which are managed by Vundle from the
+" runtimepath.
+"
+" return -- 0 (unconditionally)
 func! s:rtp_rm_a()
   let paths = map(copy(g:bundles), 'v:val.rtpath')
   let prepends = join(paths, ',')
@@ -102,6 +136,10 @@ func! s:rtp_rm_a()
   exec 'set rtp-='.fnameescape(appends)
 endf
 
+" Add all paths for the plugins which are managed by Vundle to the
+" runtimepath.
+"
+" return -- 0 (unconditionally)
 func! s:rtp_add_a()
   let paths = map(copy(g:bundles), 'v:val.rtpath')
   let prepends = join(paths, ',')
@@ -110,26 +148,54 @@ func! s:rtp_add_a()
   exec 'set rtp+='.fnameescape(appends)
 endf
 
+" Remove a directory and the corresponding 'after' directory from runtimepath.
+"
+" dir    -- the directory name to be removed as a string.  The corresponding
+"           'after' directory will also be removed.
+" return -- 0 (unconditionally)
 func! s:rtp_rm(dir) abort
   exec 'set rtp-='.fnameescape(expand(a:dir, 1))
   exec 'set rtp-='.fnameescape(expand(a:dir.'/after', 1))
 endf
 
+" Add a directory and the corresponding 'after' directory to runtimepath.
+"
+" dir    -- the directory name to be added as a string.  The corresponding
+"           'after' directory will also be added.
+" return -- 0 (unconditionally)
 func! s:rtp_add(dir) abort
   exec 'set rtp^='.fnameescape(expand(a:dir, 1))
   exec 'set rtp+='.fnameescape(expand(a:dir.'/after', 1))
 endf
 
+" Expand and simplify a path.
+"
+" path   -- the path to expand as a string
+" return -- the expanded and simplified path
 func! s:expand_path(path) abort
   return simplify(expand(a:path, 1))
 endf
 
+" Find the actual path inside a bundle directory to be added to the
+" runtimepath.  It might be provided by the user with the 'rtp' option.
+" Corresponding documentation: vundle-plugins-configure
+"
+" opts   -- a bundle dict
+" return -- expanded path to the corresponding plugin directory
 func! s:rtpath(opts)
   return has_key(a:opts, 'rtp') ? s:expand_path(a:opts.path().'/'.a:opts.rtp) : a:opts.path()
 endf
 
+" a bundle 'object'
 let s:bundle = {}
 
+" FIXME: This function is only called once and in most cases the return value
+" is stored in the bundle object as obj.rtpath unmodfied.  Is this necessary?
+"
+" Return the absolute path to the directory inside the bundle directory
+" (prefix) where thr bundle will be cloned.
+"
+" return -- the target location to clone this bundle to
 func! s:bundle.path()
   return s:expand_path(g:bundle_dir.'/'.self.name)
 endf