diff --git a/autoload/vimwiki/base.vim b/autoload/vimwiki/base.vim
index 3fc0c5b..3cd12b9 100644
--- a/autoload/vimwiki/base.vim
+++ b/autoload/vimwiki/base.vim
@@ -1,8 +1,11 @@
 " vim:tabstop=2:shiftwidth=2:expandtab:textwidth=99
 " Vimwiki autoload plugin file
 " Desc: Basic functionality
+" Called by plugin/vimwiki.vim and ftplugin/vimwiki.vim
+" by global and vimwiki local map and commands
 " Home: https://github.com/vimwiki/vimwiki/
 
+" Clause: load only once
 if exists('g:loaded_vimwiki_auto') || &compatible
   finish
 endif
@@ -12,13 +15,14 @@ let g:loaded_vimwiki_auto = 1
 let g:vimwiki_max_scan_for_caption = 5
 
 
+" Substitute regexp but do not interpret replace
 function! s:safesubstitute(text, search, replace, mode) abort
-  " Substitute regexp but do not interpret replace
   let escaped = escape(a:replace, '\&')
   return substitute(a:text, a:search, escaped, a:mode)
 endfunction
 
 
+" Get all vimwiki known syntaxes
 function! s:vimwiki_get_known_syntaxes() abort
   " Getting all syntaxes that different wikis could have
   let syntaxes = {}
@@ -35,8 +39,8 @@ function! s:vimwiki_get_known_syntaxes() abort
 endfunction
 
 
+" Get search regex from glob()
 function! vimwiki#base#file_pattern(files) abort
-  " Get search regex from glob()
   " string. Aim to support *all* special characters, forcing the user to choose
   "   names that are compatible with any external restrictions that they
   "   encounter (e.g. filesystem, wiki conventions, other syntaxes, ...).
@@ -46,7 +50,8 @@ function! vimwiki#base#file_pattern(files) abort
 endfunction
 
 
-"FIXME TODO slow and faulty
+" TODO move in path
+" FIXME TODO slow and faulty
 function! vimwiki#base#subdir(path, filename) abort
   let path = a:path
   " ensure that we are not fooled by a symbolic link
@@ -71,11 +76,13 @@ function! vimwiki#base#subdir(path, filename) abort
 endfunction
 
 
+" TODO move in path
 function! vimwiki#base#current_subdir() abort
   return vimwiki#base#subdir(vimwiki#vars#get_wikilocal('path'), expand('%:p'))
 endfunction
 
 
+" TODO move in path
 function! vimwiki#base#invsubdir(subdir) abort
   return substitute(a:subdir, '[^/\.]\+/', '../', 'g')
 endfunction
@@ -104,13 +111,14 @@ function! vimwiki#base#find_wiki(path) abort
 endfunction
 
 
-" helper: check if a link is a well formed wiki link
+" Check if a link is a well formed wiki link (Helper)
 function! s:is_wiki_link(link_infos) abort
   return a:link_infos.scheme =~# '\mwiki\d\+' || a:link_infos.scheme ==# 'diary'
 endfunction
 
 
-" THE central function of Vimwiki. Extract infos about the target from a link.
+" Extract infos about the target from a link.
+" THE central function of Vimwiki.
 " If the second parameter is present, which should be an absolute file path, it
 " is assumed that the link appears in that file. Without it, the current file
 " is used.
@@ -261,6 +269,7 @@ function! vimwiki#base#resolve_link(link_text, ...) abort
 endfunction
 
 
+" Open Link with OS handler (like gx)
 function! vimwiki#base#system_open_link(url) abort
   " handlers
   function! s:win32_handler(url) abort
@@ -314,6 +323,7 @@ function! vimwiki#base#system_open_link(url) abort
 endfunction
 
 
+" Open link with Vim (like :e)
 function! vimwiki#base#open_link(cmd, link, ...) abort
   let link_infos = {}
   if a:0
@@ -356,6 +366,8 @@ function! vimwiki#base#open_link(cmd, link, ...) abort
 endfunction
 
 
+" Escape global link
+" Called by command completion
 function! vimwiki#base#get_globlinks_escaped(...) abort
   let s_arg_lead = a:0 > 0 ? a:1 : ''
   " only get links from the current dir
@@ -381,7 +393,10 @@ function! vimwiki#base#get_globlinks_escaped(...) abort
 endfunction
 
 
-" Optional pattern argument
+" Generate wikilinks in current file
+" Called: by command VimwikiGenerateLinks (Exported)
+" Param: create: <Bool> Create links or not
+" Param: Optional pattern <String>
 function! vimwiki#base#generate_links(create, ...) abort
   " Get pattern if present
   " Globlal to script to be passed to closure
@@ -425,8 +440,8 @@ function! vimwiki#base#generate_links(create, ...) abort
     return lines
   endfunction
 
+  " Update buffer with generator super power
   let links_rx = '\%(^\s*$\)\|\%('.vimwiki#vars#get_syntaxlocal('rxListBullet').'\)'
-
   call vimwiki#base#update_listing_in_buffer(
         \ GeneratorLinks,
         \ vimwiki#vars#get_global('links_header'),
@@ -437,6 +452,8 @@ function! vimwiki#base#generate_links(create, ...) abort
 endfunction
 
 
+" Jump to other wikifile, specified on command mode
+" Called: by command VimwikiGoto (Exported)
 function! vimwiki#base#goto(...) abort
   let key = a:0 > 0 ? a:1 : input('Enter name: ')
   let anchor = a:0 > 1 ? a:2 : ''
@@ -452,6 +469,8 @@ function! vimwiki#base#goto(...) abort
 endfunction
 
 
+" Jump to previous file (backspace key)
+" Called: by VimwikiBacklinks (Exported)
 function! vimwiki#base#backlinks() abort
   let current_filename = expand('%:p')
   let locations = []
@@ -591,24 +610,29 @@ function! vimwiki#base#get_wiki_directories(wiki_nr) abort
 endfunction
 
 
+" Parse file. Returns list of all anchors
 function! vimwiki#base#get_anchors(filename, syntax) abort
+  " Clause: if not readable
   if !filereadable(a:filename)
     return []
   endif
 
+  " Get: syntax local variables
   let rxheader = vimwiki#vars#get_syntaxlocal('header_search', a:syntax)
   let rxbold = vimwiki#vars#get_syntaxlocal('bold_search', a:syntax)
   let rxtag = vimwiki#vars#get_syntaxlocal('tag_search', a:syntax)
 
+  " Init:
   let anchor_level = ['', '', '', '', '', '', '']
   let anchors = []
   let current_complete_anchor = ''
-  for line in readfile(a:filename)
 
-    " collect headers
+  for line in readfile(a:filename)
+    " Collect: headers
     let h_match = matchlist(line, rxheader)
     if !empty(h_match)
       let header = vimwiki#u#trim(h_match[2])
+      " Mesure: header level
       let level = len(h_match[1])
       call add(anchors, header)
       let anchor_level[level-1] = header
@@ -624,12 +648,13 @@ function! vimwiki#base#get_anchors(filename, syntax) abort
             let current_complete_anchor .= anchor_level[l].'#'
           endif
         endfor
+        " TODO: should not that be out of the if branch ?
         let current_complete_anchor .= header
         call add(anchors, current_complete_anchor)
       endif
     endif
 
-    " collect bold text (there can be several in one line)
+    " Collect: bold text (there can be several in one line)
     let bold_count = 1
     while 1
       let bold_text = matchstr(line, rxbold, 0, bold_count)
@@ -643,7 +668,7 @@ function! vimwiki#base#get_anchors(filename, syntax) abort
       let bold_count += 1
     endwhile
 
-    " collect tags text (there can be several in one line)
+    " Collect: tags text (there can be several in one line)
     let tag_count = 1
     while 1
       let tag_group_text = matchstr(line, rxtag, 0, tag_count)
@@ -658,13 +683,14 @@ function! vimwiki#base#get_anchors(filename, syntax) abort
       endfor
       let tag_count += 1
     endwhile
-
   endfor
 
   return anchors
 endfunction
 
 
+" Jump to anchor
+" Called by edit_file
 function! s:jump_to_anchor(anchor) abort
   let oldpos = getpos('.')
   call cursor(1, 1)
@@ -674,7 +700,6 @@ function! s:jump_to_anchor(anchor) abort
   let segments = split(anchor, '#', 0)
 
   for segment in segments
-
     let anchor_header = s:safesubstitute(
           \ vimwiki#vars#get_syntaxlocal('header_match'),
           \ '__Header__', segment, '')
@@ -694,8 +719,8 @@ function! s:jump_to_anchor(anchor) abort
 endfunction
 
 
-" Params: full path to a wiki file and its wiki number
 " Returns: a list of all links inside the wiki file
+" Params: full path to a wiki file and its wiki number
 " Every list item has the form
 " [target file, anchor, line number of the link in source file, column number]
 function! s:get_links(wikifile, idx) abort
@@ -735,6 +760,7 @@ function! s:get_links(wikifile, idx) abort
 endfunction
 
 
+" Check if all wikilinks are reachable. Answer in quickfix
 function! vimwiki#base#check_links() abort
   let anchors_of_files = {}
   let links_of_files = {}
@@ -748,6 +774,7 @@ function! vimwiki#base#check_links() abort
     endfor
   endfor
 
+  " Clean: all links: keep only file links
   for wikifile in keys(links_of_files)
     for [target_file, target_anchor, lnum, col] in links_of_files[wikifile]
       if target_file ==? '' && target_anchor ==? ''
@@ -776,7 +803,6 @@ function! vimwiki#base#check_links() abort
     endfor
   endfor
 
-
   " Check which wiki files are reachable from at least one of the index files.
   " First, all index files are marked as reachable. Then, pick a reachable file
   " and mark all files to which it links as reachable, too. Repeat until the
@@ -792,7 +818,7 @@ function! vimwiki#base#check_links() abort
     let reachable_wikifiles[wikifile] = 0
   endfor
 
-  " mark every index file as reachable
+  " Mark: every index file as reachable
   for idx in range(vimwiki#vars#number_of_wikis())
     let index_file = vimwiki#vars#get_wikilocal('path', idx) .
           \ vimwiki#vars#get_wikilocal('index', idx) . vimwiki#vars#get_wikilocal('ext', idx)
@@ -801,6 +827,7 @@ function! vimwiki#base#check_links() abort
     endif
   endfor
 
+  " Check: if files are reachable (recursively)
   while 1
     let next_unvisited_wikifile = ''
     for wf in keys(reachable_wikifiles)
@@ -820,12 +847,14 @@ function! vimwiki#base#check_links() abort
     endfor
   endwhile
 
+  " Fill: errors
   for wf in keys(reachable_wikifiles)
     if reachable_wikifiles[wf] == 0
       call add(errors, {'text':wf.' is not reachable from the index file'})
     endif
   endfor
 
+  " Fill: QuickFix list
   if empty(errors)
     echomsg 'Vimwiki: All links are OK'
   else
@@ -835,6 +864,7 @@ function! vimwiki#base#check_links() abort
 endfunction
 
 
+" Open file (like :e)
 function! vimwiki#base#edit_file(command, filename, anchor, ...) abort
   let fname = escape(a:filename, '% *|#`')
   let dir = fnamemodify(a:filename, ':p:h')
@@ -888,15 +918,17 @@ function! vimwiki#base#edit_file(command, filename, anchor, ...) abort
 endfunction
 
 
-function! vimwiki#base#search_word(wikiRx, cmd) abort
-  let match_line = search(a:wikiRx, 's'.a:cmd)
+" Search for a 1. Pattern (usually a link) with 2. flags
+" Called by find_prev_link
+function! vimwiki#base#search_word(wikiRX, flags) abort
+  let match_line = search(a:wikiRX, 's'.a:flags)
   if match_line == 0
     echomsg 'Vimwiki: Wiki link not found'
   endif
 endfunction
 
 
-" Returns part of the line that matches wikiRX at cursor
+" Return: part of the line that matches wikiRX at cursor
 function! vimwiki#base#matchstr_at_cursor(wikiRX) abort
   let col = col('.') - 1
   let line = getline('.')
@@ -920,11 +952,15 @@ function! vimwiki#base#matchstr_at_cursor(wikiRX) abort
 endfunction
 
 
+" Replace next 1. wikiRX by 2. sub
 function! vimwiki#base#replacestr_at_cursor(wikiRX, sub) abort
+  " Gather: cursor info
   let col = col('.') - 1
   let line = getline('.')
   let ebeg = -1
   let cont = match(line, a:wikiRX, 0)
+
+  " Find: link
   while (ebeg >= 0 || (0 <= cont) && (cont <= col))
     let contn = matchend(line, a:wikiRX, cont)
     if (cont <= col) && (col < contn)
@@ -934,7 +970,9 @@ function! vimwiki#base#replacestr_at_cursor(wikiRX, sub) abort
     else
       let cont = match(line, a:wikiRX, contn)
     endif
-  endwh
+  endwhile
+
+  " Replace: by sub
   if ebeg >= 0
     " TODO: There might be problems with Unicode chars...
     let newline = strpart(line, 0, ebeg).a:sub.strpart(line, ebeg+elen)
@@ -943,8 +981,10 @@ function! vimwiki#base#replacestr_at_cursor(wikiRX, sub) abort
 endfunction
 
 
+" Print list of global wiki to user
+" Called: by ui_select
 function! s:print_wiki_list() abort
-  " find the max name length for prettier formatting
+  " Find the max name length for prettier formatting
   let max_len = 0
   for idx in range(vimwiki#vars#number_of_wikis())
     let wname = vimwiki#vars#get_wikilocal('name', idx)
@@ -953,7 +993,7 @@ function! s:print_wiki_list() abort
     endif
   endfor
 
-  " print each wiki, active wiki highlighted and marked with '*'
+  " Print each wiki, active wiki highlighted and marked with '*'
   for idx in range(vimwiki#vars#number_of_wikis())
     if idx == vimwiki#vars#get_bufferlocal('wiki_nr')
       let sep = '*'
@@ -977,7 +1017,7 @@ function! s:print_wiki_list() abort
 endfunction
 
 
-" Update link: in fname.ext
+" Update link in fname.ext
 " Param: fname: the source file where to change links
 " Param: old: url regex of old path relative to wiki root
 " Param: new: url string of new path
@@ -1065,6 +1105,8 @@ function! s:update_wiki_links(wiki_nr, dir, old_url, new_url) abort
 endfunction
 
 
+" Get tail of filename
+" TODO move me in path.vim
 function! s:tail_name(fname) abort
   let result = substitute(a:fname, ':', '__colon__', 'g')
   let result = fnamemodify(result, ':t:r')
@@ -1073,6 +1115,8 @@ function! s:tail_name(fname) abort
 endfunction
 
 
+" Get list of currently open buffer that are wiki files
+" Called: by rename_link
 function! s:get_wiki_buffers() abort
   let blist = []
   let bcount = 1
@@ -1092,6 +1136,8 @@ function! s:get_wiki_buffers() abort
 endfunction
 
 
+" Edit wiki file.
+" Called: by rename_link: Usefull for buffer commands
 function! s:open_wiki_buffer(item) abort
   call vimwiki#base#edit_file(':e', a:item[0], '')
   if !empty(a:item[1])
@@ -1100,8 +1146,11 @@ function! s:open_wiki_buffer(item) abort
 endfunction
 
 
+" Helper nested syntax
+" Called: by syntax/vimwiki (exported)
+" TODO move me out of base
 function! vimwiki#base#nested_syntax(filetype, start, end, textSnipHl) abort
-" From http://vim.wikia.com/wiki/VimTip857
+  " From http://vim.wikia.com/wiki/VimTip857
   let ft=toupper(a:filetype)
   let group='textGroup'.ft
   if exists('b:current_syntax')
@@ -1164,7 +1213,7 @@ function! vimwiki#base#nested_syntax(filetype, start, end, textSnipHl) abort
 endfunction
 
 
-" creates or updates auto-generated listings in a wiki file, like TOC, diary
+" Create or update auto-generated listings in a wiki file, like TOC, diary
 " links, tags list etc.
 " - the listing consists of a header and a list of strings provided by a funcref
 " - a:content_regex is used to determine how long a potentially existing list is
@@ -1172,6 +1221,7 @@ endfunction
 "   it's not already present
 " - if a:create is true, it will be created if it doesn't exist, otherwise it
 "   will only be updated if it already exists
+" Called: by functions adding listing to buffer (this is an util function)
 function! vimwiki#base#update_listing_in_buffer(Generator, start_header,
       \ content_regex, default_lnum, header_level, create) abort
   " Vim behaves strangely when files change while in diff mode
@@ -1179,7 +1229,7 @@ function! vimwiki#base#update_listing_in_buffer(Generator, start_header,
     return
   endif
 
-  " check if the listing is already there
+  " Check if the listing is already there
   let already_there = 0
 
   let header_level = 'rxH' . a:header_level . '_Template'
@@ -1238,7 +1288,7 @@ function! vimwiki#base#update_listing_in_buffer(Generator, start_header,
 
   let start_of_listing = start_lnum
 
-  " write new listing
+  " Write new listing
   let new_header = whitespaces_in_first_line
         \ . s:safesubstitute(vimwiki#vars#get_syntaxlocal(header_level),
         \ '__Header__', a:start_header, '')
@@ -1258,7 +1308,7 @@ function! vimwiki#base#update_listing_in_buffer(Generator, start_header,
     let lines_diff += 1
   endfor
 
-  " remove empty line if end of file, otherwise append if needed
+  " Remove empty line if end of file, otherwise append if needed
   if start_lnum == line('$')
     silent exe 'keepjumps ' . start_lnum.'delete _'
   elseif start_lnum < line('$') && getline(start_lnum) !~# '\m^\s*$'
@@ -1278,17 +1328,22 @@ function! vimwiki#base#update_listing_in_buffer(Generator, start_header,
   call winrestview(winview_save)
 endfunction
 
+
+" Find next task (Exported)
 function! vimwiki#base#find_next_task() abort
   let taskRegex = vimwiki#vars#get_syntaxlocal('rxListItemWithoutCB')
     \ . '\+\(\[ \]\s\+\)\zs'
   call vimwiki#base#search_word(taskRegex, '')
 endfunction
 
+
+" Find next link (Exported)
 function! vimwiki#base#find_next_link() abort
   call vimwiki#base#search_word(vimwiki#vars#get_syntaxlocal('rxAnyLink'), '')
 endfunction
 
 
+" Find previous link (Exported)
 function! vimwiki#base#find_prev_link() abort
   "Jump 2 times if the cursor is in the middle of a link
   if synIDattr(synID(line('.'), col('.'), 0), 'name') =~# 'VimwikiLink.*' &&
@@ -1299,6 +1354,7 @@ function! vimwiki#base#find_prev_link() abort
 endfunction
 
 
+" Jump to link target (Enter press, Exported)
 function! vimwiki#base#follow_link(split, ...) abort
   let reuse_other_split_window = a:0 >= 1 ? a:1 : 0
   let move_cursor_to_new_window = a:0 >= 2 ? a:2 : 1
@@ -1394,8 +1450,9 @@ function! vimwiki#base#follow_link(split, ...) abort
 endfunction
 
 
+" Jump to previous link (Backspace press, Exported)
 function! vimwiki#base#go_back_link() abort
-  " try pop previous link from buffer list
+  " Try pop previous link from buffer list
   let prev_links = vimwiki#vars#get_bufferlocal('prev_links')
   if !empty(prev_links)
     let prev_link = remove(prev_links, 0)
@@ -1404,6 +1461,7 @@ function! vimwiki#base#go_back_link() abort
     let prev_link = []
   endif
 
+  " Jump to target with edit_file
   if !empty(prev_link)
     " go back to saved wiki link
     call vimwiki#base#edit_file(':e ', prev_link[0], '')
@@ -1415,8 +1473,8 @@ function! vimwiki#base#go_back_link() abort
 endfunction
 
 
+" Goto index file of wiki specified by index
 function! vimwiki#base#goto_index(wnum, ...) abort
-
   " if wnum = 0 the current wiki is used
   if a:wnum == 0
     let idx = vimwiki#vars#get_bufferlocal('wiki_nr')
@@ -1452,6 +1510,7 @@ function! vimwiki#base#goto_index(wnum, ...) abort
 endfunction
 
 
+" Delete current wiki file
 function! vimwiki#base#delete_link() abort
   " Delete wiki file you are in from filesystem
   let val = input('Delete "'.expand('%').'" [y]es/[N]o? ')
@@ -1577,6 +1636,8 @@ function! vimwiki#base#rename_link() abort
 endfunction
 
 
+" Spawn User Interface to select wiki project
+" Called by VimwikiUISelect (Globally Exported)
 function! vimwiki#base#ui_select() abort
   call s:print_wiki_list()
   let idx = input('Select Wiki by number and press <Enter> (empty cancels): ')
@@ -1591,6 +1652,7 @@ function! vimwiki#base#ui_select() abort
 endfunction
 
 
+" Jump to next header (Exported for text object)
 function! vimwiki#base#TO_header(inner, including_subheaders, count) abort
   let headers = s:collect_headers()
   if empty(headers)
@@ -1644,6 +1706,7 @@ function! vimwiki#base#TO_header(inner, including_subheaders, count) abort
 endfunction
 
 
+" Jump to next table cell (Exported for text object)
 function! vimwiki#base#TO_table_cell(inner, visual) abort
   if col('.') == col('$')-1
     return
@@ -1709,6 +1772,7 @@ function! vimwiki#base#TO_table_cell(inner, visual) abort
 endfunction
 
 
+" Jump to next table col (Exported for text object)
 function! vimwiki#base#TO_table_col(inner, visual) abort
   let t_rows = vimwiki#tbl#get_rows(line('.'))
   if empty(t_rows)
@@ -1824,9 +1888,12 @@ function! vimwiki#base#TO_table_col(inner, visual) abort
 endfunction
 
 
+" Increase header level (Exported)
 function! vimwiki#base#AddHeaderLevel(...) abort
+  " Clause, argument must be <= 1
+  " Actually argument is not used :-)
   if a:1 > 1
-    call vimwiki#base#AddHeaderLevel(a:1 - 1)
+    call vimwiki#base#AddHeaderLevel(1)
   endif
   let lnum = line('.')
   let line = getline(lnum)
@@ -1855,9 +1922,12 @@ function! vimwiki#base#AddHeaderLevel(...) abort
 endfunction
 
 
+" Decrease header level (Exported)
 function! vimwiki#base#RemoveHeaderLevel(...) abort
+  " Clause, argument must be <= 1
+  " Actually argument is not used :-)
   if a:1 > 1
-    call vimwiki#base#RemoveHeaderLevel(a:1 - 1)
+    call vimwiki#base#RemoveHeaderLevel(1)
   endif
   let lnum = line('.')
   let line = getline(lnum)
@@ -1891,8 +1961,7 @@ function! vimwiki#base#RemoveHeaderLevel(...) abort
 endfunction
 
 
-
-" Returns all the headers in the current buffer as a list of the form
+" Returns: all the headers in the current buffer as a list of the form
 " [[line_number, header_level, header_text], [...], [...], ...]
 function! s:collect_headers() abort
   let is_inside_pre_or_math = 0  " 1: inside pre, 2: inside math, 0: outside
@@ -1933,6 +2002,8 @@ function! s:collect_headers() abort
 endfunction
 
 
+" Returns: header index at cursor position
+" Called: by header cursor movements
 function! s:current_header(headers, line_number) abort
   if empty(a:headers)
     return -1
@@ -1950,6 +2021,8 @@ function! s:current_header(headers, line_number) abort
 endfunction
 
 
+" Returns: index of neighbor header
+" Called: by header cursor movements
 function! s:get_another_header(headers, current_index, direction, operation) abort
   if empty(a:headers) || a:current_index < 0
     return -1
@@ -1969,6 +2042,7 @@ function! s:get_another_header(headers, current_index, direction, operation) abo
 endfunction
 
 
+" Jump to parent header
 function! vimwiki#base#goto_parent_header() abort
   let headers = s:collect_headers()
   let current_header_index = s:current_header(headers, line('.'))
@@ -1981,6 +2055,7 @@ function! vimwiki#base#goto_parent_header() abort
 endfunction
 
 
+" Jump to next header
 function! vimwiki#base#goto_next_header() abort
   let headers = s:collect_headers()
   let current_header_index = s:current_header(headers, line('.'))
@@ -1994,6 +2069,7 @@ function! vimwiki#base#goto_next_header() abort
 endfunction
 
 
+" Jump to previous header
 function! vimwiki#base#goto_prev_header() abort
   let headers = s:collect_headers()
   let current_header_index = s:current_header(headers, line('.'))
@@ -2009,6 +2085,7 @@ function! vimwiki#base#goto_prev_header() abort
 endfunction
 
 
+" Jump to sibling header, next or previous (with same level)
 function! vimwiki#base#goto_sibling(direction) abort
   let headers = s:collect_headers()
   let current_header_index = s:current_header(headers, line('.'))
@@ -2023,6 +2100,7 @@ function! vimwiki#base#goto_sibling(direction) abort
 endfunction
 
 
+" Create buffer TOC (Exported)
 " a:create == 1: creates or updates TOC in current file
 " a:create == 0: update if TOC exists
 function! vimwiki#base#table_of_contents(create) abort
@@ -2132,6 +2210,7 @@ function! vimwiki#base#apply_template(template, rxUrl, rxDesc, rxStyle, rxExtens
 endfunction
 
 
+" Helper: Clean url string
 function! s:clean_url(url) abort
   " don't use an extension as part of the description
   let url = substitute(a:url, '\'.vimwiki#vars#get_wikilocal('ext').'$', '', '')
@@ -2160,6 +2239,8 @@ function! s:clean_url(url) abort
   return join(url_l, ' ')
 endfunction
 
+
+" Check if 1.filename is a diary file
 " An optional second argument allows you to pass in a list of diary files rather
 " than generating a list on each call to the function.
 function! vimwiki#base#is_diary_file(filename, ...) abort
@@ -2172,6 +2253,7 @@ function! vimwiki#base#is_diary_file(filename, ...) abort
 endfunction
 
 
+" Treat link string towards normalization
 function! vimwiki#base#normalize_link_helper(str, rxUrl, rxDesc, template) abort
   let url = matchstr(a:str, a:rxUrl)
   if vimwiki#vars#get_wikilocal('syntax') ==# 'markdown' && vimwiki#vars#get_global('markdown_link_ext')
@@ -2190,6 +2272,7 @@ function! vimwiki#base#normalize_link_helper(str, rxUrl, rxDesc, template) abort
 endfunction
 
 
+" Treat imagelink string towards normalization
 function! vimwiki#base#normalize_imagelink_helper(str, rxUrl, rxDesc, rxStyle, template) abort
   let lnk = vimwiki#base#normalize_link_helper(a:str, a:rxUrl, a:rxDesc, a:template)
   let style = matchstr(a:str, a:rxStyle)
@@ -2197,6 +2280,8 @@ function! vimwiki#base#normalize_imagelink_helper(str, rxUrl, rxDesc, rxStyle, t
   return lnk
 endfunction
 
+
+" Normalize link in a diary file
 function! vimwiki#base#normalize_link_in_diary(lnk) abort
   let sc = vimwiki#vars#get_wikilocal('links_space_char')
   let link = a:lnk . vimwiki#vars#get_wikilocal('ext')
@@ -2233,8 +2318,8 @@ function! vimwiki#base#normalize_link_in_diary(lnk) abort
 endfunction
 
 
+" Normalize link in normal mode Enter keypress
 function! s:normalize_link_syntax_n() abort
-
   " try WikiLink
   let lnk = vimwiki#base#matchstr_at_cursor(vimwiki#vars#get_syntaxlocal('rxWikiLink'))
   if !empty(lnk)
@@ -2276,10 +2361,10 @@ function! s:normalize_link_syntax_n() abort
     call vimwiki#base#replacestr_at_cursor('\V'.lnk, sub)
     return
   endif
-
 endfunction
 
 
+" Normalize link in visual mode Enter keypress
 function! s:normalize_link_syntax_v() abort
   let sel_save = &selection
   let &selection = 'old'
@@ -2309,6 +2394,7 @@ function! s:normalize_link_syntax_v() abort
 endfunction
 
 
+" Normalize link
 function! vimwiki#base#normalize_link(is_visual_mode) abort
   if exists('*vimwiki#'.vimwiki#vars#get_wikilocal('syntax').'_base#normalize_link')
     " Syntax-specific links
@@ -2324,6 +2410,8 @@ function! vimwiki#base#normalize_link(is_visual_mode) abort
 endfunction
 
 
+" Get nested syntax are present
+" Return: dictionary of syntaxes
 function! vimwiki#base#detect_nested_syntax() abort
   let last_word = '\v.*<(\w+)\s*$'
   let lines = map(filter(getline(1, '$'), 'v:val =~# "\\%({{{\\|`\\{3,\}\\|\\~\\{3,\}\\)" && v:val =~# last_word'),
@@ -2336,11 +2424,14 @@ function! vimwiki#base#detect_nested_syntax() abort
 endfunction
 
 
-function! vimwiki#base#complete_links_escaped(ArgLead, CmdLine, CursorPos) abort abort
+" Complete escaping globlinks
+function! vimwiki#base#complete_links_escaped(ArgLead, CmdLine, CursorPos) abort
   return vimwiki#base#get_globlinks_escaped(a:ArgLead)
 endfunction
 
 
+" Read caption
+" Called: by generate_links
 function! vimwiki#base#read_caption(file) abort
   let rx_header = vimwiki#vars#get_syntaxlocal('rxHeader')
 
@@ -2356,7 +2447,8 @@ function! vimwiki#base#read_caption(file) abort
 endfunction
 
 
-" For commands VimwikiSearch and VWS
+" Search for 1.pattern
+" Called by commands VimwikiSearch and VWS
 function! vimwiki#base#search(search_pattern) abort
   if empty(a:search_pattern)
     echomsg 'Vimwiki Error: No search pattern given.'
@@ -2384,6 +2476,8 @@ function! vimwiki#base#search(search_pattern) abort
   endtry
 endfunction
 
+
+" Warn deprecated feature
 function! vimwiki#base#deprecate(old, new) abort
   echohl WarningMsg
   echo a:old 'is deprecated and will be removed in future versions, use' a:new 'instead.'
@@ -2396,4 +2490,3 @@ for s:syn in s:vimwiki_get_known_syntaxes()
   execute 'runtime! autoload/vimwiki/'.s:syn.'_base.vim'
 endfor
 " -------------------------------------------------------------------------
-
diff --git a/autoload/vimwiki/diary.vim b/autoload/vimwiki/diary.vim
index 46d14ce..793c014 100644
--- a/autoload/vimwiki/diary.vim
+++ b/autoload/vimwiki/diary.vim
@@ -4,12 +4,14 @@
 " Home: https://github.com/vimwiki/vimwiki/
 
 
+" Clause: load only once
 if exists('g:loaded_vimwiki_diary_auto') || &compatible
   finish
 endif
 let g:loaded_vimwiki_diary_auto = 1
 
 
+" Add zero prefix to a number
 function! s:prefix_zero(num) abort
   if a:num < 10
     return '0'.a:num
@@ -18,12 +20,14 @@ function! s:prefix_zero(num) abort
 endfunction
 
 
+" Return: diary directory path <String>
 function! s:diary_path(...) abort
   let idx = a:0 == 0 ? vimwiki#vars#get_bufferlocal('wiki_nr') : a:1
   return vimwiki#vars#get_wikilocal('path', idx).vimwiki#vars#get_wikilocal('diary_rel_path', idx)
 endfunction
 
 
+" Return: diary index file path <String>
 function! s:diary_index(...) abort
   let idx = a:0 == 0 ? vimwiki#vars#get_bufferlocal('wiki_nr') : a:1
   return s:diary_path(idx).vimwiki#vars#get_wikilocal('diary_index', idx).
@@ -31,6 +35,7 @@ function! s:diary_index(...) abort
 endfunction
 
 
+" Return: <String> date
 function! vimwiki#diary#diary_date_link(...) abort
   if a:0
     return strftime('%Y-%m-%d', a:1)
@@ -40,6 +45,7 @@ function! vimwiki#diary#diary_date_link(...) abort
 endfunction
 
 
+" Return: <int:index, list:links>
 function! s:get_position_links(link) abort
   let idx = -1
   let links = []
@@ -56,12 +62,14 @@ function! s:get_position_links(link) abort
 endfunction
 
 
+" Convert month: number -> name
 function! s:get_month_name(month) abort
   return vimwiki#vars#get_global('diary_months')[str2nr(a:month)]
 endfunction
 
+
+" Get the first header in the file within the first s:vimwiki_max_scan_for_caption lines.
 function! s:get_first_header(fl) abort
-  " Get the first header in the file within the first s:vimwiki_max_scan_for_caption lines.
   let header_rx = vimwiki#vars#get_syntaxlocal('rxHeader')
 
   for line in readfile(a:fl, '', g:vimwiki_max_scan_for_caption)
@@ -72,9 +80,10 @@ function! s:get_first_header(fl) abort
   return ''
 endfunction
 
+
+" Get a list of all headers in a file up to a given level.
+" Return: list whose elements are pairs [level, title]
 function! s:get_all_headers(fl, maxlevel) abort
-  " Get a list of all headers in a file up to a given level.
-  " Returns a list whose elements are pairs [level, title]
   let headers_rx = {}
   for i in range(1, a:maxlevel)
     let headers_rx[i] = vimwiki#vars#get_syntaxlocal('rxH'.i.'_Text')
@@ -92,8 +101,8 @@ function! s:get_all_headers(fl, maxlevel) abort
   return headers
 endfunction
 
+" Count headers with level <=  maxlevel in a list of [level, title] pairs.
 function! s:count_headers_level_less_equal(headers, maxlevel) abort
-  " Count headers with level <=  maxlevel in a list of [level, title] pairs.
   let l:count = 0
   for [header_level, _] in a:headers
     if header_level <= a:maxlevel
@@ -103,8 +112,9 @@ function! s:count_headers_level_less_equal(headers, maxlevel) abort
   return l:count
 endfunction
 
+
+" Get the minimum level of any header in a list of [level, title] pairs.
 function! s:get_min_header_level(headers) abort
-  " The minimum level of any header in a list of [level, title] pairs.
   if len(a:headers) == 0
     return 0
   endif
@@ -116,12 +126,14 @@ function! s:get_min_header_level(headers) abort
 endfunction
 
 
+" Read all cpation in 1. <List>files
+" Return: <Dic>: key -> caption
 function! s:read_captions(files) abort
   let result = {}
   let caption_level = vimwiki#vars#get_wikilocal('diary_caption_level')
 
   for fl in a:files
-    " remove paths and extensions
+    " Remove paths and extensions
     let fl_captions = {}
 
     " Default; no captions from the file.
@@ -157,6 +169,7 @@ function! s:read_captions(files) abort
 endfunction
 
 
+" Return: <list> diary file names
 function! vimwiki#diary#get_diary_files() abort
   let rx = '^\d\{4}-\d\d-\d\d'
   let s_files = glob(vimwiki#vars#get_wikilocal('path').
@@ -171,6 +184,7 @@ function! vimwiki#diary#get_diary_files() abort
 endfunction
 
 
+" Return: <dic> nested -> links
 function! s:group_links(links) abort
   let result = {}
   let p_year = 0
@@ -193,6 +207,7 @@ function! s:group_links(links) abort
 endfunction
 
 
+" Sort list
 function! s:sort(lst) abort
   if vimwiki#vars#get_wikilocal('diary_sort') ==? 'desc'
     return reverse(sort(a:lst))
@@ -201,6 +216,8 @@ function! s:sort(lst) abort
   endif
 endfunction
 
+
+" Create note
 " The given wiki number a:wnum is 1 for the first wiki, 2 for the second and so on. This is in
 " contrast to most other places, where counting starts with 0. When a:wnum is 0, the current wiki
 " is used.
@@ -241,8 +258,9 @@ function! vimwiki#diary#make_note(wnum, ...) abort
   call vimwiki#base#open_link(cmd, link, s:diary_index(wiki_nr))
 endfunction
 
-function! vimwiki#diary#goto_diary_index(wnum) abort
 
+" Jump to diary index of 1. <Int> wikinumber
+function! vimwiki#diary#goto_diary_index(wnum) abort
   " if wnum = 0 the current wiki is used
   if a:wnum == 0
     let idx = vimwiki#vars#get_bufferlocal('wiki_nr')
@@ -267,6 +285,7 @@ function! vimwiki#diary#goto_diary_index(wnum) abort
 endfunction
 
 
+" Jump to next day
 function! vimwiki#diary#goto_next_day() abort
   let link = ''
   let [idx, links] = s:get_position_links(expand('%:t:r'))
@@ -288,6 +307,7 @@ function! vimwiki#diary#goto_next_day() abort
 endfunction
 
 
+" Jump to previous day
 function! vimwiki#diary#goto_prev_day() abort
   let link = ''
   let [idx, links] = s:get_position_links(expand('%:t:r'))
@@ -309,8 +329,8 @@ function! vimwiki#diary#goto_prev_day() abort
 endfunction
 
 
+" Create diary index content
 function! vimwiki#diary#generate_diary_section() abort
-
   let GeneratorDiary = copy(l:)
   function! GeneratorDiary.f() abort
     let lines = []
@@ -427,6 +447,7 @@ function! vimwiki#diary#calendar_action(day, month, year, week, dir) abort
 endfunction
 
 
+" Callback function for Calendar.vim
 function! vimwiki#diary#calendar_sign(day, month, year) abort
   let day = s:prefix_zero(a:day)
   let month = s:prefix_zero(a:month)
diff --git a/autoload/vimwiki/html.vim b/autoload/vimwiki/html.vim
index f50608c..976e4bb 100644
--- a/autoload/vimwiki/html.vim
+++ b/autoload/vimwiki/html.vim
@@ -1741,4 +1741,3 @@ endfunction
 function! vimwiki#html#CatUrl(wikifile) abort
   execute '!echo file://'.s:get_wikifile_url(a:wikifile)
 endfunction
-
diff --git a/autoload/vimwiki/lst.vim b/autoload/vimwiki/lst.vim
index ad2a4d5..e87c4ee 100644
--- a/autoload/vimwiki/lst.vim
+++ b/autoload/vimwiki/lst.vim
@@ -1710,4 +1710,3 @@ function! vimwiki#lst#fold_level(lnum) abort
   endif
   return '='
 endfunction
-
diff --git a/autoload/vimwiki/path.vim b/autoload/vimwiki/path.vim
index c0ce8eb..7b8bbb1 100644
--- a/autoload/vimwiki/path.vim
+++ b/autoload/vimwiki/path.vim
@@ -4,12 +4,13 @@
 " Home: https://github.com/vimwiki/vimwiki/
 
 
+" Remove: trailing /
 function! vimwiki#path#chomp_slash(str) abort
   return substitute(a:str, '[/\\]\+$', '', '')
 endfunction
 
 
-" Define path-compare function, either case-sensitive or not, depending on OS.
+" Define: path-compare function, either case-sensitive or not, depending on OS.
 if vimwiki#u#is_windows()
   function! vimwiki#path#is_equal(p1, p2) abort
     return a:p1 ==? a:p2
@@ -20,7 +21,8 @@ else
   endfunction
 endif
 
-" collapse sections like /a/b/../c to /a/c and /a/b/./c to /a/b/c
+
+" Collapse: sections like /a/b/../c to /a/c and /a/b/./c to /a/b/c
 function! vimwiki#path#normalize(path) abort
   let path = a:path
   while 1
@@ -35,6 +37,7 @@ function! vimwiki#path#normalize(path) abort
 endfunction
 
 
+" Normalize: Convert \ -> /
 function! vimwiki#path#path_norm(path) abort
   " /-slashes
   if a:path !~# '^scp:'
@@ -49,19 +52,20 @@ function! vimwiki#path#path_norm(path) abort
 endfunction
 
 
+" Check: if link is to a directory.
 function! vimwiki#path#is_link_to_dir(link) abort
-  " Check if link is to a directory.
   " It should be ended with \ or /.
   return a:link =~# '\m[/\\]$'
 endfunction
 
 
+" Return: Absolute path, from a relative link
 function! vimwiki#path#abs_path_of_link(link) abort
   return vimwiki#path#normalize(expand('%:p:h').'/'.a:link)
 endfunction
 
 
-" return longest common path prefix of 2 given paths.
+" Return: longest common path prefix of 2 given paths.
 " '~/home/usrname/wiki', '~/home/usrname/wiki/shmiki' => '~/home/usrname/wiki'
 function! vimwiki#path#path_common_pfx(path1, path2) abort
   let p1 = split(a:path1, '[/\\]', 1)
@@ -80,6 +84,7 @@ function! vimwiki#path#path_common_pfx(path1, path2) abort
 endfunction
 
 
+" Return: Relative path
 function! vimwiki#path#wikify_path(path) abort
   let result = resolve(fnamemodify(a:path, ':p'))
   if vimwiki#u#is_windows()
@@ -90,12 +95,13 @@ function! vimwiki#path#wikify_path(path) abort
 endfunction
 
 
+" Return: Current file path relative
 function! vimwiki#path#current_wiki_file() abort
   return vimwiki#path#wikify_path(expand('%:p'))
 endfunction
 
 
-" Returns: the relative path from a:dir to a:file
+" Return: the relative path from a:dir to a:file
 function! vimwiki#path#relpath(dir, file) abort
   " Check if dir here ('.') -> return file
   if empty(a:dir) || a:dir =~# '^\.[/\\]\?$'
@@ -148,6 +154,7 @@ function! vimwiki#path#relpath(dir, file) abort
 endfunction
 
 
+" Mkdir:
 " If the optional argument provided and nonzero,
 " it will ask before creating a directory
 " Returns: 1 iff directory exists or successfully created
@@ -181,6 +188,7 @@ function! vimwiki#path#mkdir(path, ...) abort
 endfunction
 
 
+" Check: if path is absolute
 function! vimwiki#path#is_absolute(path) abort
   if vimwiki#u#is_windows()
     return a:path =~? '\m^\a:'
@@ -190,7 +198,7 @@ function! vimwiki#path#is_absolute(path) abort
 endfunction
 
 
-" Combine a directory and a file into one path, doesn't generate duplicate
+" Combine: a directory and a file into one path, doesn't generate duplicate
 " path separator in case the directory is also having an ending / or \. This
 " is because on windows ~\vimwiki//.tags is invalid but ~\vimwiki/.tags is a
 " valid path.
@@ -207,4 +215,3 @@ else
     return directory . '/' . file
   endfunction
 endif
-
diff --git a/autoload/vimwiki/tags.vim b/autoload/vimwiki/tags.vim
index b3ac93f..292dfd3 100644
--- a/autoload/vimwiki/tags.vim
+++ b/autoload/vimwiki/tags.vim
@@ -1,11 +1,8 @@
 " vim:tabstop=2:shiftwidth=2:expandtab:textwidth=99
 " Vimwiki autoload plugin file
-
-
-let s:TAGS_METADATA_FILE_NAME = '.vimwiki_tags'
-
-
-
+" Description: Tag manipulation functions
+" Home: https://github.com/vimwiki/vimwiki/
+"
 " Tags metadata in-memory format:
 " metadata := { 'pagename': [entries, ...] }
 " entry := { 'tagname':..., 'lineno':..., 'link':... }
@@ -22,11 +19,13 @@ let s:TAGS_METADATA_FILE_NAME = '.vimwiki_tags'
 " of missing parameters -- "pagename" and "link".
 
 
+let s:TAGS_METADATA_FILE_NAME = '.vimwiki_tags'
 
-"   Update tags metadata.
-"   a:full_rebuild == 1: re-scan entire wiki
-"   a:full_rebuild == 0: only re-scan current page
-"   a:all_files == '':   only if the file is newer than .tags
+
+" Update tags metadata.
+" Param: a:full_rebuild == 1: re-scan entire wiki
+" Param: a:full_rebuild == 0: only re-scan current page
+" a:all_files == '':   only if the file is newer than .tags
 function! vimwiki#tags#update_tags(full_rebuild, all_files) abort
   let all_files = a:all_files !=? ''
   if !a:full_rebuild
@@ -61,14 +60,15 @@ function! vimwiki#tags#update_tags(full_rebuild, all_files) abort
 endfunction
 
 
+" Substitute regexp but do not interpret replace
+" TODO mutualize with same function in base
 function! s:safesubstitute(text, search, replace, mode) abort
-  " Substitute regexp but do not interpret replace
   let escaped = escape(a:replace, '\&')
   return substitute(a:text, a:search, escaped, a:mode)
 endfunction
 
 
-"   Scans the list of text lines (argument) and produces tags metadata as a list of tag entries.
+" Scan the list of text lines (argument) and produces tags metadata as a list of tag entries.
 function! s:scan_tags(lines, page_name) abort
 
   let entries = []
@@ -150,14 +150,14 @@ function! s:scan_tags(lines, page_name) abort
 endfunction
 
 
-"   Returns tags metadata file path
+" Return: tags metadata file path
 function! vimwiki#tags#metadata_file_path() abort
   return fnamemodify(vimwiki#path#join_path(vimwiki#vars#get_wikilocal('path'),
         \ s:TAGS_METADATA_FILE_NAME), ':p')
 endfunction
 
 
-"   Loads tags metadata from file, returns a dictionary
+" Load tags metadata from file, returns a dictionary
 function! s:load_tags_metadata() abort
   let metadata_path = vimwiki#tags#metadata_file_path()
   if !filereadable(metadata_path)
@@ -208,8 +208,8 @@ function! s:load_tags_metadata() abort
 endfunction
 
 
-"   Removes all entries for given page from metadata in-place.  Returns updated
-"   metadata (just in case).
+" Remove all entries for given page from metadata in-place.  Returns updated
+" metadata (just in case).
 function! s:remove_page_from_tags(metadata, page_name) abort
   if has_key(a:metadata, a:page_name)
     call remove(a:metadata, a:page_name)
@@ -220,7 +220,7 @@ function! s:remove_page_from_tags(metadata, page_name) abort
 endfunction
 
 
-"   Merges metadata of one file into a:metadata
+" Merge metadata of one file into a:metadata
 function! s:merge_tags(metadata, pagename, file_metadata) abort
   let metadata = a:metadata
   let metadata[a:pagename] = a:file_metadata
@@ -228,15 +228,15 @@ function! s:merge_tags(metadata, pagename, file_metadata) abort
 endfunction
 
 
-"   Compares two actual lines from tags file.  Return value is in strcmp style.
-"   See help on sort() -- that's what this function is going to be used for.
-"   See also s:write_tags_metadata below -- that's where we compose these tags
-"   file lines.
+" Compare two actual lines from tags file.  Return value is in strcmp style.
+" See help on sort() -- that's what this function is going to be used for.
+" See also s:write_tags_metadata below -- that's where we compose these tags
+" file lines.
 "
-"   This function is needed for tags sorting, since plain sort() compares line
-"   numbers as strings, not integers, and so, for example, tag at line 14
-"   preceeds the same tag on the same page at line 9.  (Because string "14" is
-"   alphabetically 'less than' string "9".)
+" This function is needed for tags sorting, since plain sort() compares line
+" numbers as strings, not integers, and so, for example, tag at line 14
+" preceeds the same tag on the same page at line 9.  (Because string "14" is
+" alphabetically 'less than' string "9".)
 function! s:tags_entry_cmp(i1, i2) abort
   let items = []
   for orig_item in [a:i1, a:i2]
@@ -260,7 +260,7 @@ function! s:tags_entry_cmp(i1, i2) abort
 endfunction
 
 
-"   Saves metadata object into a file. Throws exceptions in case of problems.
+" Save metadata object into a file. Throws exceptions in case of problems.
 function! s:write_tags_metadata(metadata) abort
   let metadata_path = vimwiki#tags#metadata_file_path()
   let tags = []
@@ -297,7 +297,7 @@ function! s:write_tags_metadata(metadata) abort
 endfunction
 
 
-"   Returns list of unique tags found in the .tags file
+" Return: list of unique tags found in the .tags file
 function! vimwiki#tags#get_tags() abort
   let metadata = s:load_tags_metadata()
   let tags = {}
@@ -310,9 +310,10 @@ function! vimwiki#tags#get_tags() abort
 endfunction
 
 
-"   Similar to vimwiki#base#generate_links.  In the current buffer, appends
-"   tags and references to all their instances.  If no arguments (tags) are
-"   specified, outputs all tags.
+" Generate tags in current buffer
+" Similar to vimwiki#base#generate_links.  In the current buffer, appends
+" tags and references to all their instances.  If no arguments (tags) are
+" specified, outputs all tags.
 function! vimwiki#tags#generate_tags(create, ...) abort
   let specific_tags = a:000
   let header_level = vimwiki#vars#get_global('tags_header_level')
@@ -396,10 +397,10 @@ function! vimwiki#tags#generate_tags(create, ...) abort
 endfunction
 
 
+" Complete tags
 function! vimwiki#tags#complete_tags(ArgLead, CmdLine, CursorPos) abort
   " We can safely ignore args if we use -custom=complete option, Vim engine
   " will do the job of filtering.
   let taglist = vimwiki#tags#get_tags()
   return join(taglist, "\n")
 endfunction
-
diff --git a/autoload/vimwiki/vars.vim b/autoload/vimwiki/vars.vim
index 0453541..3b0fc78 100644
--- a/autoload/vimwiki/vars.vim
+++ b/autoload/vimwiki/vars.vim
@@ -1,5 +1,6 @@
 " vim:tabstop=2:shiftwidth=2:expandtab:textwidth=99
 " Vimwiki autoload plugin file
+" Description: Vimwiki variable definition and manipulation
 " Home: https://github.com/vimwiki/vimwiki/
 
 
@@ -27,7 +28,6 @@
 
 
 function! s:populate_global_variables() abort
-
   let g:vimwiki_global_vars = {}
 
   call s:read_global_settings_from_user()
@@ -241,7 +241,6 @@ function! s:read_global_settings_from_user() abort
       break
     endif
   endfor
-
 endfunction
 
 
@@ -319,7 +318,6 @@ function! s:normalize_global_settings() abort
   if g:vimwiki_global_vars.use_mouse == 1 && g:vimwiki_global_vars.key_mappings.mouse == 0
     let g:vimwiki_global_vars.key_mappings.mouse = 1
   endif
-
 endfunction
 
 
@@ -518,11 +516,11 @@ function! s:normalize_wikilocal_settings() abort
       " default list margin to 0
       let wiki_settings.list_margin = 0
     endif
-
   endfor
 endfunction
 
 
+" TODO move to path
 function! s:normalize_path(path) abort
   " trim trailing / and \ because otherwise resolve() doesn't work quite right
   let path = substitute(a:path, '[/\\]\+$', '', '')
@@ -975,6 +973,12 @@ function! vimwiki#vars#get_global(key) abort
 endfunction
 
 
+function! vimwiki#vars#set_global(key, value) abort
+  let g:vimwiki_global_vars[a:key] = a:value
+  return g:vimwiki_global_vars[a:key]
+endfunction
+
+
 " the second argument can be a wiki number. When absent, the wiki of the currently active buffer is
 " used
 function! vimwiki#vars#get_wikilocal(key, ...) abort
diff --git a/ftplugin/vimwiki.vim b/ftplugin/vimwiki.vim
index b2f7a01..3e676a5 100644
--- a/ftplugin/vimwiki.vim
+++ b/ftplugin/vimwiki.vim
@@ -2,13 +2,14 @@
 " Vimwiki filetype plugin file
 " Home: https://github.com/vimwiki/vimwiki/
 
+
+" Cause: load only onces per buffer
 if exists('b:did_ftplugin')
   finish
 endif
 let b:did_ftplugin = 1  " Don't load another plugin for this buffer
 
 
-
 setlocal commentstring=%%%s
 
 if vimwiki#vars#get_global('conceallevel') && exists('+conceallevel')
@@ -22,7 +23,7 @@ setlocal isfname-=[,]
 exe 'setlocal tags+=' . escape(vimwiki#tags#metadata_file_path(), ' \|"')
 
 
-
+" Help for omnicompletion
 function! Complete_wikifiles(findstart, base) abort
   if a:findstart == 1
     let column = col('.')-2
@@ -115,8 +116,7 @@ endfunction
 setlocal omnifunc=Complete_wikifiles
 
 
-
-" settings necessary for the automatic formatting of lists
+" Declare settings necessary for the automatic formatting of lists
 setlocal autoindent
 setlocal nosmartindent
 setlocal nocindent
@@ -134,11 +134,13 @@ let &formatlistpat = vimwiki#vars#get_wikilocal('rxListItem')
 " Folding stuff
 " ------------------------------------------------
 
+" Get fold level for a list
 function! VimwikiFoldListLevel(lnum) abort
   return vimwiki#lst#fold_level(a:lnum)
 endfunction
 
 
+" Get fold level for 1. line number
 function! VimwikiFoldLevel(lnum) abort
   let line = getline(a:lnum)
 
@@ -156,7 +158,7 @@ function! VimwikiFoldLevel(lnum) abort
 endfunction
 
 
-" Constants used by VimwikiFoldText
+" Declare constants used by VimwikiFoldText
 " use \u2026 and \u21b2 (or \u2424) if enc=utf-8 to save screen space
 let s:ellipsis = (&encoding ==? 'utf-8') ? "\u2026" : '...'
 let s:ell_len = strlen(s:ellipsis)
@@ -164,18 +166,20 @@ let s:newline = (&encoding ==? 'utf-8') ? "\u21b2 " : '  '
 let s:tolerance = 5
 
 
-" unused
+" unused: too naive
 function! s:shorten_text_simple(text, len) abort
   let spare_len = a:len - len(a:text)
   return (spare_len>=0) ? [a:text,spare_len] : [a:text[0:a:len].s:ellipsis, -1]
 endfunction
 
 
+" Shorten text
+" Called: by VimwikiFoldText
 " s:shorten_text(text, len) = [string, spare] with "spare" = len-strlen(string)
 " for long enough "text", the string's length is within s:tolerance of "len"
 " (so that -s:tolerance <= spare <= s:tolerance, "string" ends with s:ellipsis)
+" Return: [string, spare]
 function! s:shorten_text(text, len) abort
-  " returns [string, spare]
   " strlen() returns lenght in bytes, not in characters, so we'll have to do a
   " trick here -- replace all non-spaces with dot, calculate lengths and
   " indexes on it, then use original string to break at selected index.
@@ -192,6 +196,7 @@ function! s:shorten_text(text, len) abort
 endfunction
 
 
+" Fold text chapter
 function! VimwikiFoldText() abort
   let line = getline(v:foldstart)
   let main_text = substitute(line, '^\s*', repeat(' ',indent(v:foldstart)), '')
@@ -528,6 +533,7 @@ if str2nr(vimwiki#vars#get_global('key_mappings').lists)
   endif
 endif
 
+" Not used
 function! s:CR(normal, just_mrkr) abort
   let res = vimwiki#tbl#kbd_cr()
   if res !=? ''
diff --git a/plugin/vimwiki.vim b/plugin/vimwiki.vim
index e43a2d7..37f9afa 100644
--- a/plugin/vimwiki.vim
+++ b/plugin/vimwiki.vim
@@ -4,6 +4,7 @@
 " GetLatestVimScripts: 2226 1 :AutoInstall: vimwiki
 
 
+" Clause: load only onces
 if exists('g:loaded_vimwiki') || &compatible
   finish
 endif
@@ -15,10 +16,11 @@ let s:plugin_vers = -1
 " Get the directory the script is installed in
 let s:plugin_dir = expand('<sfile>:p:h:h')
 
+" Save peace in the galaxy
 let s:old_cpo = &cpoptions
 set cpoptions&vim
 
-
+" Save autowriteall varaible state
 if exists('g:vimwiki_autowriteall')
   let s:vimwiki_autowriteall_saved = g:vimwiki_autowriteall
 else
@@ -26,7 +28,7 @@ else
 endif
 
 
-" this is called when the cursor leaves the buffer
+" Autocommand called when the cursor leaves the buffer
 function! s:setup_buffer_leave() abort
   " don't do anything if it's not managed by Vimwiki (that is, when it's not in
   " a registered wiki and not a temporary wiki)
@@ -42,7 +44,7 @@ function! s:setup_buffer_leave() abort
 endfunction
 
 
-" create a new temporary wiki for the current buffer
+" Create a new temporary wiki for the current buffer
 function! s:create_temporary_wiki() abort
   let path = expand('%:p:h')
   let ext = '.'.expand('%:e')
@@ -67,7 +69,7 @@ function! s:create_temporary_wiki() abort
 endfunction
 
 
-" This function is called when Vim opens a new buffer with a known wiki
+" Autocommand called when Vim opens a new buffer with a known wiki
 " extension. Both when the buffer has never been opened in this session and
 " when it has.
 function! s:setup_new_wiki_buffer() abort
@@ -94,7 +96,7 @@ function! s:setup_new_wiki_buffer() abort
 endfunction
 
 
-" this is called when the cursor enters the buffer
+" Autocommand called when the cursor enters the buffer
 function! s:setup_buffer_enter() abort
   " don't do anything if it's not managed by Vimwiki (that is, when it's not in
   " a registered wiki and not a temporary wiki)
@@ -106,7 +108,7 @@ function! s:setup_buffer_enter() abort
 endfunction
 
 
-" this is called when the buffer enters a window or when running a  diff
+" Autocommand called when the buffer enters a window or when running a  diff
 function! s:setup_buffer_win_enter() abort
   " don't do anything if it's not managed by Vimwiki (that is, when it's not in
   " a registered wiki and not a temporary wiki)
@@ -122,6 +124,7 @@ function! s:setup_buffer_win_enter() abort
 endfunction
 
 
+" Help syntax reloading
 function! s:setup_cleared_syntax() abort
   " highlight groups that get cleared
   " on colorscheme change because they are not linked to Vim-predefined groups
@@ -140,6 +143,7 @@ function! s:setup_cleared_syntax() abort
 endfunction
 
 
+" Return: list of extension known vy vimwiki
 function! s:vimwiki_get_known_extensions() abort
   " Getting all extensions that different wikis could have
   let extensions = {}
@@ -193,7 +197,7 @@ function! s:set_windowlocal_options() abort
     endif
   endif
 
-  if vimwiki#vars#get_global('conceallevel') && exists('+conceallevel')
+  if exists('+conceallevel')
     let &l:conceallevel = vimwiki#vars#get_global('conceallevel')
   endif
 
@@ -203,6 +207,8 @@ function! s:set_windowlocal_options() abort
 endfunction
 
 
+" Echo vimwiki version
+" Called by :VimwikiShowVersion
 function! s:get_version() abort
   if s:plugin_vers != -1
     echo 'Stable version: ' . string(s:plugin_vers)
@@ -223,10 +229,10 @@ function! s:get_version() abort
 endfunction
 
 
-
-" Initialization of Vimwiki starts here. Make sure everything below does not
-" cause autoload/vimwiki/base.vim to be loaded
-
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+" Initialization of Vimwiki starts here.
+" Make sure everything below does not cause autoload/vimwiki/base.vim
+" to be loaded
 call vimwiki#vars#init()
 
 
@@ -251,7 +257,7 @@ if !exists('*VimwikiWikiIncludeHandler')
 endif
 
 
-" write a level 1 header to new wiki files
+" Write a level 1 header to new wiki files
 " a:fname should be an absolute filepath
 function! s:create_h1(fname) abort
   if vimwiki#vars#get_global('auto_header')
@@ -297,7 +303,6 @@ function! s:create_h1(fname) abort
 endfunction
 
 " Define autocommands for all known wiki extensions
-
 let s:known_extensions = s:vimwiki_get_known_extensions()
 
 if index(s:known_extensions, '.wiki') > -1
@@ -341,6 +346,7 @@ augroup vimwiki
 augroup END
 
 
+" Declare global commands
 command! VimwikiUISelect call vimwiki#base#ui_select()
 
 " these commands take a count e.g. :VimwikiIndex 2
@@ -375,6 +381,7 @@ command! VimwikiDiaryGenerateLinks
 command! VimwikiShowVersion call s:get_version()
 
 
+" Declare global maps
 " <Plug> global definitions
 nnoremap <silent><script> <Plug>VimwikiIndex
     \ :<C-U>call vimwiki#base#goto_index(v:count)<CR>
@@ -397,10 +404,11 @@ nnoremap <silent><script> <Plug>VimwikiMakeTomorrowDiaryNote
     \ :<C-U>call vimwiki#diary#make_note(v:count, 0,
     \ vimwiki#diary#diary_date_link(localtime() + 60*60*24))<CR>
 
-" get the user defined prefix (default <leader>w)
+" Get the user defined prefix (default <leader>w)
 let s:map_prefix = vimwiki#vars#get_global('map_prefix')
 
-" default global key mappings
+
+" Set default global key mappings
 if str2nr(vimwiki#vars#get_global('key_mappings').global)
   call vimwiki#u#map_key('n', s:map_prefix . 'w', '<Plug>VimwikiIndex', 2)
   call vimwiki#u#map_key('n', s:map_prefix . 't', '<Plug>VimwikiTabIndex', 2)
@@ -414,6 +422,7 @@ if str2nr(vimwiki#vars#get_global('key_mappings').global)
 endif
 
 
+" Build global wiki menu (GUI)
 function! s:build_menu(topmenu) abort
   let wnamelist = []
   for idx in range(vimwiki#vars#number_of_wikis())
@@ -442,6 +451,8 @@ function! s:build_menu(topmenu) abort
   endfor
 endfunction
 
+
+" Build global table menu (GUI)
 function! s:build_table_menu(topmenu) abort
   exe 'menu '.a:topmenu.'.-Sep- :'
   exe 'menu '.a:topmenu.'.Table.Create\ (enter\ cols\ rows) :VimwikiTable '
@@ -453,6 +464,7 @@ function! s:build_table_menu(topmenu) abort
 endfunction
 
 
+" Build Menus now
 if !empty(vimwiki#vars#get_global('menu'))
   call s:build_menu(vimwiki#vars#get_global('menu'))
   call s:build_table_menu(vimwiki#vars#get_global('menu'))
@@ -466,4 +478,5 @@ if vimwiki#vars#get_global('use_calendar')
 endif
 
 
+" Restore peace in the galaxy
 let &cpoptions = s:old_cpo