mirrors/Vundle
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Complete function documentation

Browse Source 
- Complete the code documentation effort started by @lucc
- Remove some judgemental comments ✨
- Remove comments pertaining to things that should be opened as issues
- Boxed ❗
This commit is contained in:
Jacobo de Vera
2014-04-10 23:50:05 +02:00
parent b3b5f529b3
commit 87e5a19520
3 changed files with 151 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
autoload/vundle/installer.vim
View File

@@ -1,9 +1,10 @@
" ---------------------------------------------------------------------------
" 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 :
@@ -12,22 +13,23 @@ 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.
" This calls '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().
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 = ''
@@ -59,6 +61,8 @@ func! s:process(bang, cmd)
echo 'Done! '.msg
endf
" ---------------------------------------------------------------------------
" Call another function in the different Vundle windows.
"
" func_name -- the function to call
@@ -66,6 +70,7 @@ endf
" ... -- 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
@@ -106,11 +111,13 @@ 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
@@ -119,11 +126,14 @@ 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, {})
@@ -132,11 +142,14 @@ 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
@@ -152,9 +165,12 @@ 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
@@ -163,11 +179,14 @@ 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)')
@@ -183,11 +202,13 @@ 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)
@@ -195,12 +216,14 @@ 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")))
@@ -231,12 +254,15 @@ 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'))) ?
@@ -260,10 +286,13 @@ 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'))
@@ -272,10 +301,13 @@ 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/')
@@ -289,6 +321,8 @@ 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
@@ -298,6 +332,7 @@ endf
" '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()
@@ -343,11 +378,14 @@ 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') . '"'
@@ -355,10 +393,13 @@ 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
@@ -368,21 +409,27 @@ 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'