Shift vorbisenc API docs into doxygen 2/2 (add doxygen)

Shift vorbisenc API docs into doxygen 2/2 (add doxygen)

Until now the libvorbisenc API has been documented via static html
pages in doc/vorbisenc/.  This patch moves that documentation into the
vorbisenc.h header.

For the most part, the text was copied unchanged, except where doxygen
was better able to say something in its own way.  For example, the
\deprecated tag changed the format of deprecation messages.  A few
trivial misspelling's were fixed, including some that doxygen caught.
Some of the narrative flow of the original was lost, as doxygen
reorders documentation according to its own plan, so I changed a few
phrases on account of this loss of context.

Some ordinary comments in the header were obviated by the doxygen and
removed.

Neither the overview documentation in overview.html nor the examples
in examples.html are included in the header, nor are the functions
that are exposed by including vorbisenc.h but which are actually
declared in codecs.h.

Patch from Douglas Bagnall <douglas@paradise.net.nz>.

svn path=/trunk/vorbis/; revision=16789