Add missing function documentation

Pretty thin as far as documentation goes, but better than nothing.

diff --git a/README.md b/README.md
index 31dfb942a0f7c5b1b562d02fef13503dc942aa84..28ab86756e5f29e56b6508609a125a16f1828240 100644 (file)
--- a/README.md
+++ b/README.md
@@ -31,6 +31,89 @@ To generate help tags under Pathogen, you can do so from inside Vim with:
 ```
 
 
+## Functions<a name="pinnacle-functions" href="#user-content-pinnacle-functions"></a>
+
+<p align="right"><a name="pinnaclesubnewlines" href="#user-content-pinnaclesubnewlines"><code>pinnacle#sub_newlines()</code></a></p>
+
+### `pinnacle#sub_newlines()`<a name="pinnacle-pinnaclesubnewlines" href="#user-content-pinnacle-pinnaclesubnewlines"></a>
+
+Replaces newlines with spaces.
+
+<p align="right"><a name="pinnaclecapturelline" href="#user-content-pinnaclecapturelline"><code>pinnacle#capturel_line()</code></a></p>
+
+### `pinnacle#capturel_line()`<a name="pinnacle-pinnaclecapturelline" href="#user-content-pinnacle-pinnaclecapturelline"></a>
+
+Runs a command and returns the captured output as a single line.
+
+Useful when we don't want to let long lines on narrow windows produce unwanted embedded newlines.
+
+<p align="right"><a name="pinnaclecapturehighlight" href="#user-content-pinnaclecapturehighlight"><code>pinnacle#capture_highlight()</code></a></p>
+
+### `pinnacle#capture_highlight()`<a name="pinnacle-pinnaclecapturehighlight" href="#user-content-pinnacle-pinnaclecapturehighlight"></a>
+
+Gets the current value of a highlight group.
+
+<p align="right"><a name="pinnacleextracthighlight" href="#user-content-pinnacleextracthighlight"><code>pinnacle#extract_highlight()</code></a></p>
+
+### `pinnacle#extract_highlight()`<a name="pinnacle-pinnacleextracthighlight" href="#user-content-pinnacle-pinnacleextracthighlight"></a>
+
+Extracts a highlight string from a group, recursively traversing linked groups, and returns a string suitable for passing to `:highlight`.
+
+<p align="right"><a name="pinnacleextractbg" href="#user-content-pinnacleextractbg"><code>pinnacle#extract_bg()</code></a></p>
+
+### `pinnacle#extract_bg()`<a name="pinnacle-pinnacleextractbg" href="#user-content-pinnacle-pinnacleextractbg"></a>
+
+Extracts just the bg portion of the specified highlight group.
+
+<p align="right"><a name="pinnacleextractfg" href="#user-content-pinnacleextractfg"><code>pinnacle#extract_fg()</code></a></p>
+
+### `pinnacle#extract_fg()`<a name="pinnacle-pinnacleextractfg" href="#user-content-pinnacle-pinnacleextractfg"></a>
+
+Extracts just the bg portion of the specified highlight group.
+
+<p align="right"><a name="pinnacleextractcomponent" href="#user-content-pinnacleextractcomponent"><code>pinnacle#extract_component()</code></a></p>
+
+### `pinnacle#extract_component()`<a name="pinnacle-pinnacleextractcomponent" href="#user-content-pinnacle-pinnacleextractcomponent"></a>
+
+Extracts a single component (eg. &quot;bg&quot;, &quot;fg&quot;, &quot;italic&quot; etc) from the specified highlight group.
+
+<p align="right"><a name="pinnacledump" href="#user-content-pinnacledump"><code>pinnacle#dump()</code></a></p>
+
+### `pinnacle#dump()`<a name="pinnacle-pinnacledump" href="#user-content-pinnacle-pinnacledump"></a>
+
+Returns a dictionary representation of the specified highlight group.
+
+<p align="right"><a name="pinnaclehighlight" href="#user-content-pinnaclehighlight"><code>pinnacle#highlight()</code></a></p>
+
+### `pinnacle#highlight()`<a name="pinnacle-pinnaclehighlight" href="#user-content-pinnacle-pinnaclehighlight"></a>
+
+Returns a string representation of a dictionary containing bg, fg, term, cterm and guiterm entries.
+
+<p align="right"><a name="pinnacleitalicize" href="#user-content-pinnacleitalicize"><code>pinnacle#italicize()</code></a></p>
+
+### `pinnacle#italicize()`<a name="pinnacle-pinnacleitalicize" href="#user-content-pinnacle-pinnacleitalicize"></a>
+
+Returns an italicized copy of `group` suitable for passing to `:highlight`.
+
+<p align="right"><a name="pinnacleembolden" href="#user-content-pinnacleembolden"><code>pinnacle#embolden()</code></a></p>
+
+### `pinnacle#embolden()`<a name="pinnacle-pinnacleembolden" href="#user-content-pinnacle-pinnacleembolden"></a>
+
+Returns a bold copy of `group` suitable for passing to `:highlight`.
+
+<p align="right"><a name="pinnacleunderline" href="#user-content-pinnacleunderline"><code>pinnacle#underline()</code></a></p>
+
+### `pinnacle#underline()`<a name="pinnacle-pinnacleunderline" href="#user-content-pinnacle-pinnacleunderline"></a>
+
+Returns an underlined copy of `group` suitable for passing to `:highlight`.
+
+<p align="right"><a name="pinnacledecorate" href="#user-content-pinnacledecorate"><code>pinnacle#decorate()</code></a></p>
+
+### `pinnacle#decorate()`<a name="pinnacle-pinnacledecorate" href="#user-content-pinnacle-pinnacledecorate"></a>
+
+Returns a copy of `group` decorated with `style` (eg. &quot;bold&quot;, &quot;italic&quot; etc) suitable for passing to `:highlight`.
+
+
 ## Website<a name="pinnacle-website" href="#user-content-pinnacle-website"></a>
 
 The official Pinnacle source code repo is at:

diff --git a/autoload/pinnacle.vim b/autoload/pinnacle.vim
index 4cdc44333514c292ea7f68440ad02585a5a1e920..8b7ead589108ea4a8fd96b417d27a21221737591 100644 (file)
--- a/autoload/pinnacle.vim
+++ b/autoload/pinnacle.vim
@@ -33,6 +33,7 @@
 " :call pathogen#helptags()
 " ```
 "
+" @footer
 "
 " # Website
 "
@@ -151,15 +152,23 @@
 "
 " - Initial release.
 
+""
+" @function pinnacle#sub_newlines
+"
 " Replaces newlines with spaces.
+"
 function! pinnacle#sub_newlines(string) abort
   return tr(a:string, "\r\n", '  ')
 endfunction
 
+""
+" @function pinnacle#capturel_line
+"
 " Runs a command and returns the captured output as a single line.
 "
 " Useful when we don't want to let long lines on narrow windows produce unwanted
 " embedded newlines.
+"
 function! pinnacle#capture_line(command) abort
   redir => l:capture
   execute a:command
@@ -168,13 +177,21 @@ function! pinnacle#capture_line(command) abort
   return pinnacle#sub_newlines(l:capture)
 endfunction
 
+""
+" @function pinnacle#capture_highlight
+"
 " Gets the current value of a highlight group.
+"
 function! pinnacle#capture_highlight(group) abort
   return pinnacle#capture_line('0verbose silent highlight ' . a:group)
 endfunction
 
+""
+" @function pinnacle#extract_highlight
+"
 " Extracts a highlight string from a group, recursively traversing linked
 " groups, and returns a string suitable for passing to `:highlight`.
+"
 function! pinnacle#extract_highlight(group) abort
   let l:group = pinnacle#capture_highlight(a:group)
 
@@ -193,19 +210,39 @@ endfunction
 
 let s:prefix=has('gui') || (has('termguicolors') && &termguicolors) ? 'gui' : 'cterm'
 
+""
+" @function pinnacle#extract_bg
+"
+" Extracts just the bg portion of the specified highlight group.
+"
 function! pinnacle#extract_bg(group) abort
   return pinnacle#extract_component(a:group, 'bg')
 endfunction
 
+""
+" @function pinnacle#extract_fg
+"
+" Extracts just the bg portion of the specified highlight group.
+"
 function! pinnacle#extract_fg(group) abort
   return pinnacle#extract_component(a:group, 'fg')
 endfunction
 
+""
+" @function pinnacle#extract_component
+"
+" Extracts a single component (eg. "bg", "fg", "italic" etc) from the specified
+" highlight group.
+"
 function! pinnacle#extract_component(group, component) abort
   return synIDattr(synIDtrans(hlID(a:group)), a:component)
 endfunction
 
+""
+" @function pinnacle#dump
+"
 " Returns a dictionary representation of the specified highlight group.
+"
 function! pinnacle#dump(highlight) abort
   return filter({
         \   'bg': pinnacle#extract_component(a:highlight, 'bg'),
@@ -224,8 +261,12 @@ function! pinnacle#dump(highlight) abort
         \ }, 'v:val != ""')
 endfunction
 
+""
+" @function pinnacle#highlight
+"
 " Returns a string representation of a dictionary containing bg, fg, term, cterm
 " and guiterm entries.
+"
 function! pinnacle#highlight(highlight) abort
   let l:result=[]
   if has_key(a:highlight, 'bg')
@@ -246,23 +287,39 @@ function! pinnacle#highlight(highlight) abort
   return join(l:result, ' ')
 endfunction
 
+""
+" @function pinnacle#italicize
+"
 " Returns an italicized copy of `group` suitable for passing to `:highlight`.
+"
 function! pinnacle#italicize(group) abort
   return pinnacle#decorate('italic', a:group)
 endfunction
 
+""
+" @function pinnacle#embolden
+"
 " Returns a bold copy of `group` suitable for passing to `:highlight`.
+"
 function! pinnacle#embolden(group) abort
   return pinnacle#decorate('bold', a:group)
 endfunction
 
+""
+" @function pinnacle#underline
+"
 " Returns an underlined copy of `group` suitable for passing to `:highlight`.
+"
 function! pinnacle#underline(group) abort
   return pinnacle#decorate('underline', a:group)
 endfunction
 
+""
+" @function pinnacle#decorate
+"
 " Returns a copy of `group` decorated with `style` (eg. "bold", "italic" etc)
 " suitable for passing to `:highlight`.
+"
 function! pinnacle#decorate(style, group) abort
   let l:original = pinnacle#extract_highlight(a:group)
 

diff --git a/doc/pinnacle.txt b/doc/pinnacle.txt
index 9eff568b697aba2d3a66329208d29d6670f453dc..107c8565735893c89382c44248ec83b37b4a43f1 100644 (file)
--- a/doc/pinnacle.txt
+++ b/doc/pinnacle.txt
@@ -4,11 +4,12 @@ CONTENTS                                                     *pinnacle-contents*
 
 1. Intro             |pinnacle-intro|
 2. Installation      |pinnacle-installation|
-3. Website           |pinnacle-website|
-4. License           |pinnacle-license|
-5. Development       |pinnacle-development|
-6. Authors           |pinnacle-authors|
-7. History           |pinnacle-history|
+3. Functions         |pinnacle-functions|
+4. Website           |pinnacle-website|
+5. License           |pinnacle-license|
+6. Development       |pinnacle-development|
+7. Authors           |pinnacle-authors|
+8. History           |pinnacle-history|
 
 INTRO                                                           *pinnacle-intro*
 
@@ -35,6 +36,67 @@ To generate help tags under Pathogen, you can do so from inside Vim with:
 >
     :call pathogen#helptags()
 <
+FUNCTIONS                                                   *pinnacle-functions*
+
+pinnacle#sub_newlines()                                *pinnacle#sub_newlines()*
+
+Replaces newlines with spaces.
+
+pinnacle#capturel_line()                              *pinnacle#capturel_line()*
+
+Runs a command and returns the captured output as a single line.
+
+Useful when we don't want to let long lines on narrow windows produce
+unwanted embedded newlines.
+
+pinnacle#capture_highlight()                      *pinnacle#capture_highlight()*
+
+Gets the current value of a highlight group.
+
+pinnacle#extract_highlight()                      *pinnacle#extract_highlight()*
+
+Extracts a highlight string from a group, recursively traversing linked
+groups, and returns a string suitable for passing to `:highlight`.
+
+pinnacle#extract_bg()                                    *pinnacle#extract_bg()*
+
+Extracts just the bg portion of the specified highlight group.
+
+pinnacle#extract_fg()                                    *pinnacle#extract_fg()*
+
+Extracts just the bg portion of the specified highlight group.
+
+pinnacle#extract_component()                      *pinnacle#extract_component()*
+
+Extracts a single component (eg. "bg", "fg", "italic" etc) from the
+specified highlight group.
+
+pinnacle#dump()                                                *pinnacle#dump()*
+
+Returns a dictionary representation of the specified highlight group.
+
+pinnacle#highlight()                                      *pinnacle#highlight()*
+
+Returns a string representation of a dictionary containing bg, fg, term,
+cterm and guiterm entries.
+
+pinnacle#italicize()                                      *pinnacle#italicize()*
+
+Returns an italicized copy of `group` suitable for passing to `:highlight`.
+
+pinnacle#embolden()                                        *pinnacle#embolden()*
+
+Returns a bold copy of `group` suitable for passing to `:highlight`.
+
+pinnacle#underline()                                      *pinnacle#underline()*
+
+Returns an underlined copy of `group` suitable for passing to `:highlight`.
+
+pinnacle#decorate()                                        *pinnacle#decorate()*
+
+Returns a copy of `group` decorated with `style` (eg. "bold", "italic" etc)
+suitable for passing to `:highlight`.
+
 WEBSITE                                                       *pinnacle-website*
 
 The official Pinnacle source code repo is at: