VimDoxSpell
===========
         Current Web home: http://rtfb.lt/projects/vim-dox-spell/

VimDoxSpell is a sample program and a collection of sample files to make
your Vim editor be nice^H^H^H^H VERY nice about doxygen comments in your
source files.

It contains a patched doxygen.vim script that comes with Vim itself.
The patch fixes some problems I had. Having doxygen comment highlighting
fixed, this package aims to solve another frequent problem in source code
editing: spell checker's false positives on program identifiers. This is
solved by converting the tags file into additional Vim's spelling dictionary.

This package is intended to be an "almost working" sample with exhaustive
documentation. The "almost" part comes from the nature of the problem at
hand: you should base your personal solution on this sample, adopting it
to your particular needs in your unique development environment.

This software is in public domain. It is intended to be customized by
its nature. This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

I would appreciate being acknowledged in any derived work. Any comments,
suggestions, corrections or patches are welcome. Even hate-mail will be
well met, not to mention fan-mail :-)

Please report bugs in VimDoxSpell to Vytautas.Shaltenis@gmail.com.

VimDoxSpell's home page is at
<http://rtfb.lt/projects/vim-dox-spell/>.

MAINTAINER: Vytautas Saltenis <Vytautas.Shaltenis@gmail.com>

Copyright (C) 2008, Vytautas Saltenis

Using VimDoxSpell
=================

This package is intended to be a sample and a guide. Start by examining
vimrc-sample and setting up your Vim editor. As a part of configuration,
copy doxygen.vim to Vim's syntax directory, i.e. do this:

$ mkdir -p ~/.vim/syntax
$ cp doxygen.vim ~/.vim/syntax

My changes for this file have not yet been reviewed by the maintainer of the
syntax script.

Next, figure out how do you want to generate tags for your code base.
Ideally, this should be done somewhere in your scripts that pull from
repositories, so that the tags file is always up to date.

Now figure out where doxygen puts its XML files. These can be used to
extend your dictionary with the names of groups of your functions. If your
documentation does not rely on explicit grouping, you can edit the script
to skip this part.

Call tagstospl.py script with paths to your tags and index.html files. If you
wish, incorporate a call to this script into your build process, right after
the call to doxygen.

You're done! You can now launch your beloved editor and happily check the
spelling of your documentation. No more false positives!

Note: If your documentation contains a lot of references to some fixed
API (e.g. you're writing a game and you mention OpenGL functions a lot),
it might prove useful to hack in an additional step of merging two tags
files: one for your code base, and one for the headers of the API.

Warning: All this is nice, but be careful, though. If your code is likely
to contain things that are likely typos of the usual words, you might shoot
yourself in a foot. A good example if a famous variable name "wnd". It is
likely to be a typo for "end" in your documentation. It won't be detected,
because the spell checker will think you're referring to the variable.

Files
=====

vimrc-sample: a sample vimrc file with relevant settings and explanations

doxygen.vim: a patched Vim syntax script. It should be copied to the syntax
             folder of the editor. Don't forget to backup the original!

tags-sample: tags generated from you code base. I use Exuberant Ctags
(http://ctags.sourceforge.net).

index-sample.xml: a sample of index.xml that is generated by doxygen.

tagstospl.py: the smart part of this package. A script to generate the
              dictionary to be used to eliminate false positives.

c-files/: directory with test/sample C files. The "code base".