So far, we've had our plugin all within one file. Let's see how we can break it down into multiple files to keep our newly created project organized! Give a look at the list in Plugin layout section of this chapter.

First, you can see that the ftplugin/ directory contains filetype-specific plugin configuration. Right now, most of our plugin is actually pretty independent from working with Python, except for the s:comment_string variable. Let's move it out to <...>/vim-commenter/ftplugin/python.vim:

" String representing inline Python comments.
let g:commenter#comment_str = '# '

We've changed the scope from s: to g: (since the variable is now used in different scripts), and added the commenter# namespace to avoid namespace collision.

The name should also be updated in <...>/vim-commenter/plugin/commenter.vim. Now might be a good time to test those substitution commands you learned earlier in this book:

:%s/<s:comment_string>/g:commenter#comment_str/g

Another directory of interest is autoload/. Currently, whenever Vim starts, it will parse and load g:commenter#ToggleComment. That's not very fast. Instead, we can choose to move the function to the autoload/ directory. The name of the file needs to correspond to its namespace; in this case, it's commenter. Let's create <...>/vim-commenter/autoload/commenter.vim:

" Comment out the current line in Python.
function! g:commenter#ToggleComment()
  let l:i = indent('.') " Number of spaces.
  let l:line = getline('.')
  let l:cur_row = getcurpos()[1]
  let l:cur_col = getcurpos()[2]
  let l:prefix = l:i > 0 ? l:line[:l:i - 1] : '' " Handle 0 indent cases.
 if l:line[l:i:l:i + len(g:commenter#comment_str) - 1] ==
     g:commenter#comment_str
  call setline('.', l:prefix .
         l:line[l:i + len(g:commenter#comment_str):])
    let l:cur_offset = -len(g:commenter#comment_str)
  else
    call setline('.', l:prefix . g:commenter#comment_str . l:line[l:i:])
    let l:cur_offset = len(g:commenter#comment_str)
  endif
  call cursor(l:cur_row, l:cur_col + l:cur_offset)
endfunction

At this point, the only thing left in <...>/vim-commenter/plugin/commenter.vim is the mapping:

nnoremap gc :call g:commenter#ToggleComment()<cr>

Here's how our plugin will get loaded when a user is working with Vim:

• User opens Vim, and <...>/vim-commenter/plugin/commenter.vim is loaded. Our gc mapping is now registered.
• User opens a Python file, and <...>/vim-commenter/ftplugin/python.vim is loaded. g:commenter#comment_str is initialized.
• User runs gc, which loads and executes g:commenter#ToggleComment within <...>/vim-commenter/autoload/commenter.vim.

One directory we haven't given much love to yet is doc/. Vim is known for having extensive documentation, and we have a recommendation to uphold this. Let's add <...>/vim-commenter/doc/commenter.txt:

*commenter.txt* Our first commenting plugin.
*commenter*

=========================================================================
CONTENTS                                             *commenter-contents*

  1. Intro..............................................|commenter-intro|
  2. Usage..............................................|commenter-usage|

=========================================================================
1. Intro                                                *commenter-intro*

Have you ever wanted to comment out a line with only three presses of a
button? Now you can! A new and wonderful vim-commenter lets you comment
out a single line in Python quickly!

2. Usage                                                *commenter-usage*

This wonderful plugin supports the following key bindings:

  gc: toggle comment on a current line

That's it for now. Thanks for reading!

  vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:

Vim help has its own format, but here are some highlights:

• *help-tag* is used to denote a help tag. Whenever you run :help help-tag, Vim takes you to a file containing *help-tag*, and places the cursor right at the tag.
• Text...|help-tag| is used for navigation within a help file. It lets the reader jump to the desired tags from this section.
• All the === lines are just for pretty looks. They don't actually mean anything.
• A line like vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl: lets you tell Vim how to display a file when editing it (all of these are options you can set using the set keyword). This becomes really useful for files without clearly identifiable filetypes (such as .txt files).

You can learn more about Vim's help format by reading :help help-writing. The easiest thing though is to find some popular plugins and copy what they do.

After you finished writing the doc, you'll need to tell Vim to generate its help tags in order for the entries to be indexed by the :help command. Run the following:

:helptags ~/.vim/pack/plugins/start/vim-commenter/doc

Now, you'll be able to visit entries you added to the help file:

:help commenter-intro

Here's a screenshot of Vim help taking you to the requested section: