Instead of having Doxyfile.in configured by Autoconf, the Doxyfile
can have the tags that need to be configured piped into the doxygen
command through stdin with the overrides after Doxyfile's contents.
Going forward, the documentation should be generated in two different
modes: liblzma or internal.
liblzma is useful for most users. It is the documentation for just
the liblzma API header files. This is the default.
internal is for people who want to understand how xz and liblzma work.
It might be useful for people who want to contribute to the project.
A few Doxygen tags were obsolete from 1.4.7. Version 1.8.17 released
in 2019, so this should be compatible with resonable modern distros.
The purpose of Doxygen these days is for docs on the website, so it
doesn't necessarily have to work for everyone. Just when the maintainers
want to update the docs.
Doxygen is now configurable in autotools only with
--enable-doxygen=[api|all]. The default is "api", which will only
generate HTML output for liblzma API functions. The LaTex documentation
output was also disabled.
Currently the file list generated by Doxygen has src/ at the
beginning of each path. Paths like common/sysdefs.h and
liblzma/api/lzma.h are easier to read without such a prefix.
Builds from a separate build directory with
mkdir build
cd build
../configure
doxygen Doxyfile
include an even longer prefix /home/someone/src/xz/src; this
patch has the nice side-effect of eliminating that prefix, too.
Fixes: http://bugs.debian.org/572273
lots of comments from Doxygen.
It seems that the Doxygen authors' intent is to not apply
their copyright on generated files, but since it doesn't
matter for XZ Utils at all, better safe than sorry.
