improve documentation for writing extensions, also add helper methods.

autoload/airline/extensions.vim

@@ -26,6 +26,26 @@ let s:filetype_overrides = {
 
 let s:filetype_regex_overrides = {}
 
+function! s:check_defined_section(name)
+  if !exists('w:airline_section_{a:name}')
+    if g:airline_section_{a:name} == '__'
+      let w:airline_section_{a:name} = ''
+    else
+      let w:airline_section_{a:name} = g:airline_section_{a:name}
+    endif
+  endif
+endfunction
+
+function! airline#extensions#append_to_section(name, value)
+  call <sid>check_defined_section(a:name)
+  let w:airline_section_{a:name} .= a:value
+endfunction
+
+function! airline#extensions#prepend_to_section(name, value)
+  call <sid>check_defined_section(a:name)
+  let w:airline_section_{a:name} = a:value . w:airline_section_{a:name}
+endfunction
+
 function! airline#extensions#apply_left_override(section1, section2)
   let w:airline_section_a = a:section1
   let w:airline_section_b = a:section2
@@ -166,14 +186,13 @@ function! airline#extensions#load()
   endif
 
   if g:airline_section_warning == '__'
+    if (get(g:, 'airline#extensions#whitespace#enabled', 1) && get(g:, 'airline_detect_whitespace', 1))
+      call airline#extensions#whitespace#init(s:ext)
+    endif
     if (get(g:, 'airline#extensions#syntastic#enabled', 1) && get(g:, 'airline_enable_syntastic', 1))
           \ && exists(':SyntasticCheck')
       call airline#extensions#syntastic#init(s:ext)
     endif
-
-    if (get(g:, 'airline#extensions#whitespace#enabled', 1) && get(g:, 'airline_detect_whitespace', 1))
-      call airline#extensions#whitespace#init(s:ext)
-    endif
   endif
 
   if get(g:, 'airline#extensions#readonly#enabled', 1)

autoload/airline/extensions/csv.vim

@@ -16,13 +16,8 @@ endfunction
 
 function! airline#extensions#csv#apply(...)
   if &ft ==# "csv"
-    if !exists('w:airline_section_gutter')
-      let w:airline_section_gutter = '%='
-    endif
-    let w:airline_section_gutter =
-          \ g:airline_left_alt_sep
-          \ .' %{airline#extensions#csv#get_column()}'
-          \ .w:airline_section_gutter
+    call airline#extensions#prepend_to_section('gutter',
+          \ g:airline_left_alt_sep.' %{airline#extensions#csv#get_column()}')
   endif
 endfunction
 

autoload/airline/extensions/example.vim

@@ -6,33 +6,35 @@ if !exists('g:airline#extensions#example#number_of_cats')
   let g:airline#extensions#example#number_of_cats = 42
 endif
 
-" First you should follow the convention and define an 'init' function.
-" It takes a single argument, which is the 'ext'ension manager of sorts,
-" which you can invoke certain functions.  The most important one is
-" 'add_statusline_func', which as the name implies, adds a function to
-" the collection such that it will be invoked prior to changes being made
-" to the statusline. Finally, invoke this init function in the
-" 'extensions.vim' file after a check to a non-autoloaded variable,
-" command, or function.
+" There are predominantly two methods for integrating a plugin into
+" vim-airline.  The first method here simply modifies the global section and
+" appends information to it.  This is useful for cases where the information
+" should be displayed all the time for all filetypes.
+function! airline#extensions#example#init(ext)
+  let g:airline_section_y .= '%{airline#extensions#example#get_cats()}'
+endfunction
+
+" The second method involves using the 'ext'ension manager that was passed in
+" and appends a name of a function.  This function will be invoked just prior
+" to updating the statusline.  This method is useful for plugin-specific
+" statuslines (like NERDTree or Tagbar) or language specific plugins (like
+" virtualenv) which do not need to be loaded all the time.
 function! airline#extensions#example#init(ext)
   call a:ext.add_statusline_func('airline#extensions#example#apply')
 
-  " Alternatively, you can also modify the default global section by
-  " appending or prepending to it.  But read on to see why using the funcref
-  " method is preferred.
-  let g:airline_section_y .= '%{airline#extensions#example#nyancat()}'
+  " There is also the following function for making changes just prior to an
+  " inactive statusline.
+  " call a:ext.add_inactive_statusline_func('airline#extensions#example#unapply')
 endfunction
 
+" This function will be invoked just prior to the statusline getting modified.
 function! airline#extensions#example#apply(...)
-  " Here we are checking for the filetype, allowing for the extension to
-  " be loaded only in certain cases.
+  " First we check for the filetype.
   if &filetype == "nyancat"
-
-    " Then we define a window-local variable, which overrides the default
-    " g: variable.
-    let w:airline_section_gutter =
-          \ g:airline_section_gutter
-          \ .' %{airline#extensions#example#get_cats()}'
+    " Let's use a helper function.  It will take care of ensuring that the
+    " window-local override exists (and create one based on the global
+    " airline_section if not), and prepend to it.
+    call airline#extensions#prepend_to_section('x', '%{airline#extensions#example#get_cats()} ')
   endif
 endfunction
 

autoload/airline/extensions/syntastic.vim

@@ -2,8 +2,7 @@
 " vim: et ts=2 sts=2 sw=2
 
 function! airline#extensions#syntastic#apply(...)
-  let w:airline_section_warning = get(w:, 'airline_section_warning', '')
-  let w:airline_section_warning = ' %{SyntasticStatuslineFlag()}'
+  call airline#extensions#append_to_section('warning', '%{SyntasticStatuslineFlag()}')
 endfunction
 
 function! airline#extensions#syntastic#init(ext)

autoload/airline/extensions/whitespace.vim

@@ -54,10 +54,7 @@ function! airline#extensions#whitespace#check()
 endfunction!
 
 function! airline#extensions#whitespace#apply(...)
-  if !exists('w:airline_section_warning')
-    let w:airline_section_warning = ' '
-  endif
-  let w:airline_section_warning .= '%{airline#extensions#whitespace#check()}'
+  call airline#extensions#append_to_section('warning', ' %{airline#extensions#whitespace#check()}')
 endfunction
 
 function! airline#extensions#whitespace#toggle()