More inline function documentation :-)

README.md

@@ -236,33 +236,113 @@ Recently this plug-in switched from reimplementing [:mksession][mksession] to ac
 <!-- Start of generated documentation -->
 
 The documentation of the 34 functions below was extracted from
-2 Vim scripts on June 24, 2013 at 22:18.
+2 Vim scripts on June 24, 2013 at 22:49.
 
 ### Public API for vim-notes plug-in
 
+#### The `xolox#session#save_session()` function
+
+Save the current Vim editing session to a Vim script using the
+[:mksession] [] command and some additional Vim magic provided by the
+vim-session plug-in. When the generated session script is later sourced
+using the [:source] [] command (possibly in another process or even on
+another machine) it will restore the editing session to its previous state
+(provided all of the files involved in the session are still there at
+their original locations).
+
+The first argument is expected to be a list, it will be extended with the
+lines to be added to the session script. The second argument is expected
+to be the filename under which the script will later be saved (it's
+embedded in a comment at the top of the script).
+
+[:mksession]: http://vimdoc.sourceforge.net/htmldoc/starting.html#:mksession
+[:source]: http://vimdoc.sourceforge.net/htmldoc/repeat.html#:source
+
+#### The `xolox#session#save_globals()` function
+
+Serialize the values of the global variables configured by the user with
+the `g:session_persist_globals` option. The first argument is expected to
+be a list, it will be extended with the lines to be added to the session
+script.
+
+#### The `xolox#session#save_features()` function
+
+Save the current state of the following Vim features:
+
+- Whether syntax highlighting is enabled (`:syntax on`)
+- Whether file type detection is enabled (`:filetype on`)
+- Whether file type plug-ins are enabled (`:filetype plugin on`)
+- Whether file type indent plug-ins are enabled (`:filetype indent on`)
+
+The first argument is expected to be a list, it will be extended with the
+lines to be added to the session script.
+
+#### The `xolox#session#save_colors()` function
+
+Save the current color scheme and background color. The first argument is
+expected to be a list, it will be extended with the lines to be added to
+the session script.
+
+#### The `xolox#session#save_fullscreen()` function
+
+Save the full screen state of Vim. This function provides integration
+between my [vim-session] [] and [vim-shell] [] plug-ins. The first
+argument is expected to be a list, it will be extended with the lines to
+be added to the session script.
+
+[vim-session]: http://peterodding.com/code/vim/session
+[vim-shell]: http://peterodding.com/code/vim/shell
+
+#### The `xolox#session#save_qflist()` function
+
+Save the contents of the quick-fix list. The first argument is expected to
+be a list, it will be extended with the lines to be added to the session
+script.
+
+#### The `xolox#session#save_state()` function
+
+Wrapper for the [:mksession] [] command that slightly massages the
+generated Vim script to get rid of some strange quirks in the way Vim
+generates sessions. Also implements support for buffers with content that
+was generated by other Vim plug-ins. The first argument is expected to
+be a list, it will be extended with the lines to be added to the session
+script.
+
 #### The `xolox#session#save_special_windows()` function
 
-Integration between :mksession, :NERDTree and :Project.
+Implements support for buffers with content that was generated by other
+Vim plug-ins. The first argument is expected to be a list, it will be
+extended with the lines to be added to the session script.
 
 #### The `xolox#session#auto_load()` function
 
-Automatically load the default / last used session when Vim starts.
+Automatically load the default or last used session when Vim starts.
+Normally called by the [VimEnter] [] automatic command event.
+
+[VimEnter]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#VimEnter
 
 #### The `xolox#session#auto_save()` function
 
-We won't save the session if Vim is not terminating normally.
+Automatically save the current editing session when Vim is closed.
+Normally called by the [VimLeavePre] [] automatic command event.
+
+[VimLeavePre]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#VimLeavePre
 
 #### The `xolox#session#auto_save_periodic()` function
 
-Automatically save the session every few minutes?
+Automatically saves the current editing session every few minutes.
+Normally called by the [CursorHold] [] and [CursorHoldI] [] automatic
+command events.
 
-#### The `xolox#session#auto_unlock()` function
+[CursorHold]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHold
+[CursorHoldI]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHoldI
 
-Automatically unlock all sessions when Vim quits.
+#### The `xolox#session#auto_unlock()` function
 
-#### The `xolox#session#view_cmd()` function
+Automatically unlock all sessions when Vim quits. Normally called by the
+[VimLeavePre] [] automatic command event.
 
-Name of session given as command argument?
+[VimLeavePre]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#VimLeavePre
 
 #### The `xolox#session#prompt_for_name()` function
 

autoload/xolox/session.vim

@@ -15,6 +15,21 @@ let g:xolox#session#version = '2.4.3'
 " argument:
 
 function! xolox#session#save_session(commands, filename) " {{{2
+  " Save the current Vim editing session to a Vim script using the
+  " [:mksession] [] command and some additional Vim magic provided by the
+  " vim-session plug-in. When the generated session script is later sourced
+  " using the [:source] [] command (possibly in another process or even on
+  " another machine) it will restore the editing session to its previous state
+  " (provided all of the files involved in the session are still there at
+  " their original locations).
+  "
+  " The first argument is expected to be a list, it will be extended with the
+  " lines to be added to the session script. The second argument is expected
+  " to be the filename under which the script will later be saved (it's
+  " embedded in a comment at the top of the script).
+  "
+  " [:mksession]: http://vimdoc.sourceforge.net/htmldoc/starting.html#:mksession
+  " [:source]: http://vimdoc.sourceforge.net/htmldoc/repeat.html#:source
   let is_all_tabs = xolox#session#include_tabs()
   call add(a:commands, '" ' . a:filename . ':')
   call add(a:commands, '" Vim session script' . (is_all_tabs ? '' : ' for a single tab page') . '.')
@@ -54,12 +69,25 @@ function! xolox#session#save_session(commands, filename) " {{{2
 endfunction
 
 function! xolox#session#save_globals(commands) " {{{2
+  " Serialize the values of the global variables configured by the user with
+  " the `g:session_persist_globals` option. The first argument is expected to
+  " be a list, it will be extended with the lines to be added to the session
+  " script.
   for global in g:session_persist_globals
     call add(a:commands, printf("let %s = %s", global, string(eval(global))))
   endfor
 endfunction
 
 function! xolox#session#save_features(commands) " {{{2
+  " Save the current state of the following Vim features:
+  "
+  " - Whether syntax highlighting is enabled (`:syntax on`)
+  " - Whether file type detection is enabled (`:filetype on`)
+  " - Whether file type plug-ins are enabled (`:filetype plugin on`)
+  " - Whether file type indent plug-ins are enabled (`:filetype indent on`)
+  "
+  " The first argument is expected to be a list, it will be extended with the
+  " lines to be added to the session script.
   let template = "if exists('%s') != %i | %s %s | endif"
   for [global, command] in [
           \ ['g:syntax_on', 'syntax'],
@@ -73,6 +101,9 @@ function! xolox#session#save_features(commands) " {{{2
 endfunction
 
 function! xolox#session#save_colors(commands) " {{{2
+  " Save the current color scheme and background color. The first argument is
+  " expected to be a list, it will be extended with the lines to be added to
+  " the session script.
   call add(a:commands, 'if &background != ' . string(&background))
   call add(a:commands, "\tset background=" . &background)
   call add(a:commands, 'endif')
@@ -83,6 +114,13 @@ function! xolox#session#save_colors(commands) " {{{2
 endfunction
 
 function! xolox#session#save_fullscreen(commands) " {{{2
+  " Save the full screen state of Vim. This function provides integration
+  " between my [vim-session] [] and [vim-shell] [] plug-ins. The first
+  " argument is expected to be a list, it will be extended with the lines to
+  " be added to the session script.
+  "
+  " [vim-session]: http://peterodding.com/code/vim/session
+  " [vim-shell]: http://peterodding.com/code/vim/shell
   try
     let commands = xolox#shell#persist_fullscreen()
     if !empty(commands)
@@ -104,6 +142,9 @@ function! xolox#session#save_fullscreen(commands) " {{{2
 endfunction
 
 function! xolox#session#save_qflist(commands) " {{{2
+  " Save the contents of the quick-fix list. The first argument is expected to
+  " be a list, it will be extended with the lines to be added to the session
+  " script.
   if has('quickfix')
     let qf_list = []
     for qf_entry in getqflist()
@@ -120,6 +161,12 @@ function! xolox#session#save_qflist(commands) " {{{2
 endfunction
 
 function! xolox#session#save_state(commands) " {{{2
+  " Wrapper for the [:mksession] [] command that slightly massages the
+  " generated Vim script to get rid of some strange quirks in the way Vim
+  " generates sessions. Also implements support for buffers with content that
+  " was generated by other Vim plug-ins. The first argument is expected to
+  " be a list, it will be extended with the lines to be added to the session
+  " script.
   let tempfile = tempname()
   let ssop_save = &sessionoptions
   try
@@ -217,7 +264,9 @@ function! s:state_filter(line) " {{{3
 endfunction
 
 function! xolox#session#save_special_windows(session) " {{{2
-  " Integration between :mksession, :NERDTree and :Project.
+  " Implements support for buffers with content that was generated by other
+  " Vim plug-ins. The first argument is expected to be a list, it will be
+  " extended with the lines to be added to the session script.
   let tabpage = tabpagenr()
   let window = winnr()
   let s:nerdtrees = {}
@@ -315,7 +364,10 @@ endfunction
 " Automatic commands to manage the default session. {{{1
 
 function! xolox#session#auto_load() " {{{2
-  " Automatically load the default / last used session when Vim starts.
+  " Automatically load the default or last used session when Vim starts.
+  " Normally called by the [VimEnter] [] automatic command event.
+  "
+  " [VimEnter]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#VimEnter
   if g:session_autoload == 'no'
     return
   endif
@@ -359,12 +411,16 @@ function! xolox#session#auto_load() " {{{2
 endfunction
 
 function! xolox#session#auto_save() " {{{2
-  " We won't save the session if Vim is not terminating normally.
+  " Automatically save the current editing session when Vim is closed.
+  " Normally called by the [VimLeavePre] [] automatic command event.
+  "
+  " [VimLeavePre]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#VimLeavePre
   if v:dying
+    " We won't save the session if Vim is not terminating normally.
     return
   endif
-  " We won't save the session if auto-save is explicitly disabled.
   if g:session_autosave == 'no'
+    " We won't save the session if auto-save is explicitly disabled.
     return
   endif
   " Get the name of the active session (if any).
@@ -389,7 +445,12 @@ function! xolox#session#auto_save() " {{{2
 endfunction
 
 function! xolox#session#auto_save_periodic() " {{{2
-  " Automatically save the session every few minutes?
+  " Automatically saves the current editing session every few minutes.
+  " Normally called by the [CursorHold] [] and [CursorHoldI] [] automatic
+  " command events.
+  "
+  " [CursorHold]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHold
+  " [CursorHoldI]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#CursorHoldI
   if g:session_autosave_periodic > 0
     let interval = g:session_autosave_periodic * 60
     let next_save = s:session_last_flushed + interval
@@ -418,7 +479,10 @@ if !exists('s:session_last_flushed')
 endif
 
 function! xolox#session#auto_unlock() " {{{2
-  " Automatically unlock all sessions when Vim quits.
+  " Automatically unlock all sessions when Vim quits. Normally called by the
+  " [VimLeavePre] [] automatic command event.
+  "
+  " [VimLeavePre]: http://vimdoc.sourceforge.net/htmldoc/autocmd.html#VimLeavePre
   let i = 0
   while i < len(s:lock_files)
     let lock_file = s:lock_files[i]
@@ -481,7 +545,6 @@ function! xolox#session#open_cmd(name, bang, command) abort " {{{2
 endfunction
 
 function! xolox#session#view_cmd(name) abort " {{{2
-  " Name of session given as command argument?
   let name = s:unescape(a:name)
   " Default to the current session?
   if empty(name)