Nitpicky tweaks

README.md

@@ -152,9 +152,27 @@ If all comments look like the one in the screenshot above, you have enabled ital
 
 ### Customizing onedark.vim's look without forking the repository
 
-onedark.vim exposes a function called `onedark#set_highlight` that you can call from within your `~/.vimrc` in order to customize the look of onedark.vim by overriding its defaults.
+onedark.vim exposes `onedark#extend_highlight` and `onedark#set_highlight` functions that you can call from within your `~/.vimrc` in order to customize the look of onedark.vim.
 
-The function's first argument should be the name of a highlight group, and its second argument should be style data.
+#### `onedark#extend_highlight`
+
+`onedark#extend_highlight` allows you to customize individual aspects of onedark.vim's existing highlight groups, overriding only the keys you provide. (To completely redefine/override an existing highlight group, see `onedark#set_highlight` below.)
+
+`onedark#extend_highlight`'s first argunment should be the name of a highlight group, and its second argument should be style data.
+
+For example, if you want functions to be bold only in GUI mode, place the following lines **before** the `colorscheme onedark` line in your `~/.vimrc`:
+
+```vim
+if (has("autocmd") && has("gui_running"))
+  autocmd ColorScheme * call onedark#extend_highlight("Function", { "gui": "bold" })
+end
+```
+
+#### `onedark#set_highlight`
+
+`onedark#set_highlight` allows you to completely redefine/override highlight groups of your choosing.
+
+`onedark#set_highlight`'s first argument should be the name of a highlight group, and its second argument should be style data.
 
 For example, to remove the background color only when running in terminals (outside GUI mode and for use in transparent terminals,) place the following lines **before** the `colorscheme onedark` line in your `~/.vimrc`:
 
@@ -170,12 +188,7 @@ if (has("autocmd") && !has("gui_running"))
 end
 ```
 
-If you want to change only some parts of highlight group, you can use `onedark#extend_highlight` that will change only keys you provide. For example, if you want functions to be bold in GUI, you can do something like this:
-```vim
-call onedark#extend_highlight("Function", { "gui": "bold" })
-```
-
-You can also override a color across all highlights by adding the color definitions to the `g:onedark_color_overrides` dictionary in your `~/.vimrc` like so:
+Finally, you can also override a color across all highlights by adding color definitions to the `g:onedark_color_overrides` dictionary in your `~/.vimrc` like so:
 
 ```vim
 let g:onedark_color_overrides = {

colors/onedark.vim

@@ -52,7 +52,6 @@ endif
 set t_Co=256
 
 let g:colors_name="onedark"
-let s:group_colors = {}
 
 " Set to "256" for 256-color terminals, or
 " set to "16" to use your terminal emulator's native colors
@@ -70,8 +69,10 @@ endif
 
 " This function is based on one from FlatColor: https://github.com/MaxSt/FlatColor/
 " Which in turn was based on one found in hemisu: https://github.com/noahfrederick/vim-hemisu/
+let s:group_colors = {} " Cache of default highlight group settings, for later reference via `onedark#extend_highlight`
 function! s:h(group, style, ...)
   let a:highlight = a:0 > 0 ? extend(s:group_colors[a:group], a:style) : a:style
+
   if g:onedark_terminal_italics == 0
     if has_key(a:highlight, "cterm") && a:highlight["cterm"] == "italic"
       unlet a:highlight.cterm
@@ -88,6 +89,7 @@ function! s:h(group, style, ...)
     let l:ctermfg = (has_key(a:highlight, "fg") ? a:highlight.fg.cterm : "NONE")
     let l:ctermbg = (has_key(a:highlight, "bg") ? a:highlight.bg.cterm : "NONE")
   endif
+
   execute "highlight" a:group
     \ "guifg="   (has_key(a:highlight, "fg")    ? a:highlight.fg.gui   : "NONE")
     \ "guibg="   (has_key(a:highlight, "bg")    ? a:highlight.bg.gui   : "NONE")
@@ -96,6 +98,7 @@ function! s:h(group, style, ...)
     \ "ctermfg=" . l:ctermfg
     \ "ctermbg=" . l:ctermbg
     \ "cterm="   (has_key(a:highlight, "cterm") ? a:highlight.cterm    : "NONE")
+
   let s:group_colors[a:group] = a:highlight
 endfunction