update documentation.

autoload/airline/extensions.vim

@@ -28,12 +28,8 @@ 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)

autoload/airline/extensions/example.vim

@@ -6,24 +6,18 @@ if !exists('g:airline#extensions#example#number_of_cats')
   let g:airline#extensions#example#number_of_cats = 42
 endif
 
-" 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.
+" First we define an init function that will be invoked from extensions.vim
 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)
+  " Here we define a new part for the plugin.  This allows users to place this
+  " extension in arbitrary locations.
+  let g:airline_parts.cats = '%{airline#extensions#example#get_cats()}'
+
+  " Next up we add a funcref so that we can run some code prior to the
+  " statusline getting modifed.
   call a:ext.add_statusline_func('airline#extensions#example#apply')
 
-  " There is also the following function for making changes just prior to an
-  " inactive statusline.
+  " You can also add a funcref for inactive statuslines.
   " call a:ext.add_inactive_statusline_func('airline#extensions#example#unapply')
 endfunction
 
@@ -34,7 +28,7 @@ function! airline#extensions#example#apply(...)
     " 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()} ')
+    call airline#extensions#prepend_to_section('x', g:airline_parts.cats)
   endif
 endfunction
 

autoload/airline/extensions/whitespace.vim

@@ -61,6 +61,7 @@ function! airline#extensions#whitespace#toggle()
     call airline#extensions#whitespace#init()
     let s:enabled = 1
   endif
+  echo 'Whitespace checking: '.(s:enabled ? 'Enabled' : 'Disabled')
 endfunction
 
 function! airline#extensions#whitespace#init(...)

doc/airline.txt

@@ -168,11 +168,11 @@ extension.
 >
   variable names                default contents
   ----------------------------------------------------------------------------
-  let g:airline_section_a       (the mode/paste indicator)
-  let g:airline_section_b       (the fugitive/lawrencium branch indicator)
+  let g:airline_section_a       (mode, paste, iminsert)
+  let g:airline_section_b       (hunks, branch)
   let g:airline_section_c       (bufferline or filename)
   let g:airline_section_gutter  (readonly, csv)
-  let g:airline_section_x       (tagbar, virtualenv, filetype)
+  let g:airline_section_x       (tagbar, filetype, virtualenv)
   let g:airline_section_y       (fileencoding, fileformat)
   let g:airline_section_z       (percentage, line number, column number)
   let g:airline_section_warning (syntastic, whitespace)
@@ -309,23 +309,29 @@ temporary override. >
 PIPELINE                                                  *airline-pipeline*
 
 Sometimes you want to do more than just use overrides.  The statusline funcref
-is invoked and passed a bunch of arguments.  The first of these arguments is
-the statusline builder.  You can use this to build completely custom
-statuslines to your liking.  Here is an example: >
+is invoked and passed two arguments.  The first of these arguments is the
+statusline builder.  You can use this to build completely custom statuslines
+to your liking.  Here is an example: >
 >
   function! MyPlugin(...)
     " first variable is the statusline builder
     let builder = a:1
 
-    " build and set the statusline
     " WARNING: the API for the builder is not finalized and may change
     call builder.add_section('Normal', '%f')
     call builder.add_section('WarningMsg', '%{getcwd()}')
-    call setwinvar(winnr(), '&statusline', builder.build())
+    call builder.split()
+    call builder.add_section('airline_z', '%p%%')
 
-    return -1
+    " tell the core to use the contents of the builder
+    return 1
   endfunction
 <
+The above example uses various some example highlight groups to demonstrate
+that you can make any combination from the loaded colorscheme.  However, if
+you want colors to change between modes, you should use one of the section
+highlight groups, e.g. `airline_a` and `airline_b`.
+
 The second variable is the context, which is a dictionary containing various
 values such as whether the statusline is active or not, and the window number.
 >
@@ -334,7 +340,6 @@ values such as whether the statusline is active or not, and the window number.
     'active': 'whether the window is active or not',
   }
 <
-
                                              *airline-pipeline-return-codes*
 The pipeline accepts various return codes and can be used to determine the
 next action.  The following are the supported codes: >
@@ -374,6 +379,9 @@ For contributions into the plugin, here are the following guidelines:
   b.  Configuration variables for the extension should reside in the
       extension, e.g. `g:airline#extensions#foo_plugin#bar_variable`.
 
+  c.  A value should be added to the `g:airline_parts` dictionary such that
+      the extension can be arbitrarily positioned.
+
 See the source of |example.vim| for a working extension.
 
 ==============================================================================