Complete function documentation

- Complete the code documentation effort started by @lucc
- Remove some judgemental comments ✨
- Remove comments pertaining to things that should be opened as issues
- Boxed ❗

autoload/vundle/config.vim

@@ -1,8 +1,10 @@
+" ---------------------------------------------------------------------------
 " 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,24 +18,36 @@ func! vundle#config#bundle(arg, ...)
   return bundle
 endf
 
+
+" ---------------------------------------------------------------------------
+"  When lazy bundle load is used (begin/end functions), add all configured
+"  bundles to runtimepath and reorder appropriately.
+" ---------------------------------------------------------------------------
 func! vundle#config#activate_bundles()
   call s:rtp_add_a()
   call s:rtp_add_defaults()
 endf
 
+
+" ---------------------------------------------------------------------------
 " Initialize Vundle.
 "
-" return -- 0 (unconditionally)
+" Start a new bundles list and make sure the runtimepath does not contain
+" directories from a previous call. In theory, this should only be called
+" once.
+" ---------------------------------------------------------------------------
 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)
@@ -46,11 +60,14 @@ 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 . "'"
@@ -61,12 +78,15 @@ 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
@@ -78,13 +98,16 @@ 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'
@@ -108,6 +131,12 @@ func! s:parse_name(arg)
   return {'name': name, 'uri': uri, 'name_spec': arg }
 endf
 
+
+" ---------------------------------------------------------------------------
+"  Modify the runtimepath, after all bundles have been added, so that the
+"  directories that were in the default runtimepath appear first in the list
+"  (with their 'after' directories last).
+" ---------------------------------------------------------------------------
 func! s:rtp_add_defaults()
   let current = &rtp
   set rtp&vim
@@ -124,10 +153,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, ',')
@@ -136,10 +165,11 @@ 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, ',')
@@ -148,58 +178,77 @@ 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
 
+
+" ---------------------------------------------------------------------------
+"  Determine if the bundle has the pinned attribute set in the config
+"
+"  return -- 1 if the bundle is pinned, 0 otherwise
+" ---------------------------------------------------------------------------
 func! s:bundle.is_pinned()
   return get(self, 'pinned')
 endf