build(docs): use doxygen_add_docs()

I had originally done this in #662, but never re-submitted it.
06aa271 reminded me that I should also
include Doxygen documentation in the Debian package, so I took a bit of
time to re-prepare this patch.

Using CMake's doxygen_add_docs() isn't only more concise and idiomatic,
it also solves actual issues of Doxygen-generated documentation. Without
this patch, the generated docs include an absolute path of the build
directory; apart from being ugly, it also creates issues with
reproducibility, as it is required to rebuild the package in the same
exact directory to get a bit-by-bit identical copy of the package.

CMake is able to work around this Doxygen quirk, and the generated HTML
only includes relative paths.

The documentation gets now output to build/html/ instead of
build/docs/html/.

Here's a full diff of the generated output before and after applying
this patch:

    diff html_no_patch_dot/cubeb_8h.html html_dot/cubeb_8h.html
    8c8
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h File Reference</title>
    ---
    > <title>cubeb: include/cubeb/cubeb.h File Reference</title>
    87,92c87,92
    < <div class="center"><img src="cubeb_8h__incl.png" border="0" usemap="#a_2tmp_2tmp_8ils_at_y7fk0_2up_2cubeb_2include_2cubeb_2cubeb_8h" alt=""/></div>
    < <map name="a_2tmp_2tmp_8ils_at_y7fk0_2up_2cubeb_2include_2cubeb_2cubeb_8h" id="a_2tmp_2tmp_8ils_at_y7fk0_2up_2cubeb_2include_2cubeb_2cubeb_8h">
    < <area shape="rect" title="The libcubeb C API." alt="" coords="99,5,277,61"/>
    < <area shape="rect" title=" " alt="" coords="5,109,128,136"/>
    < <area shape="rect" title=" " alt="" coords="153,109,223,136"/>
    < <area shape="rect" title=" " alt="" coords="247,109,318,136"/>
    ---
    > <div class="center"><img src="cubeb_8h__incl.png" border="0" usemap="#ainclude_2cubeb_2cubeb_8h" alt=""/></div>
    > <map name="ainclude_2cubeb_2cubeb_8h" id="ainclude_2cubeb_2cubeb_8h">
    > <area shape="rect" title="The libcubeb C API." alt="" coords="105,5,271,32"/>
    > <area shape="rect" title=" " alt="" coords="5,80,128,107"/>
    > <area shape="rect" title=" " alt="" coords="153,80,223,107"/>
    > <area shape="rect" title=" " alt="" coords="247,80,318,107"/>
    diff html_no_patch_dot/cubeb_8h__incl.map html_dot/cubeb_8h__incl.map
    1,5c1,5
    < <map id="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h" name="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h">
    < <area shape="rect" id="node1" title="The libcubeb C API." alt="" coords="99,5,277,61"/>
    < <area shape="rect" id="node2" title=" " alt="" coords="5,109,128,136"/>
    < <area shape="rect" id="node3" title=" " alt="" coords="153,109,223,136"/>
    < <area shape="rect" id="node4" title=" " alt="" coords="247,109,318,136"/>
    ---
    > <map id="include/cubeb/cubeb.h" name="include/cubeb/cubeb.h">
    > <area shape="rect" id="node1" title="The libcubeb C API." alt="" coords="105,5,271,32"/>
    > <area shape="rect" id="node2" title=" " alt="" coords="5,80,128,107"/>
    > <area shape="rect" id="node3" title=" " alt="" coords="153,80,223,107"/>
    > <area shape="rect" id="node4" title=" " alt="" coords="247,80,318,107"/>
    diff html_no_patch_dot/cubeb_8h__incl.md5 html_dot/cubeb_8h__incl.md5
    1c1
    < 80f3c1becd2984dea59dbcc5f43d8bc7
    \ No newline at end of file
    ---
    > bd73bf4d2f8603949fb7021f1b7e2758
    \ No newline at end of file
    Binary files html_no_patch_dot/cubeb_8h__incl.png and html_dot/cubeb_8h__incl.png differ
    diff html_no_patch_dot/cubeb_8h_source.html html_dot/cubeb_8h_source.html
    8c8
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/cubeb.h Source File</title>
    ---
    > <title>cubeb: include/cubeb/cubeb.h Source File</title>
    diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860.html html_dot/dir_4a77ea686d101b1caa0240510cb36860.html
    8c8
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb Directory Reference</title>
    ---
    > <title>cubeb: include/cubeb Directory Reference</title>
    75c75
    < <div class="center"><img src="dir_4a77ea686d101b1caa0240510cb36860_dep.png" border="0" usemap="#adir__4a77ea686d101b1caa0240510cb36860__dep" alt="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb"/></div>
    ---
    > <div class="center"><img src="dir_4a77ea686d101b1caa0240510cb36860_dep.png" border="0" usemap="#adir__4a77ea686d101b1caa0240510cb36860__dep" alt="include/cubeb"/></div>
    diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.map html_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.map
    1c1
    < <map id="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb" name="/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb">
    ---
    > <map id="include/cubeb" name="include/cubeb">
    diff html_no_patch_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.md5 html_dot/dir_4a77ea686d101b1caa0240510cb36860_dep.md5
    1c1
    < d2b3a541ded19d569e3456d07b13bfca
    \ No newline at end of file
    ---
    > ba94d8d8e5033c1685cddf5e6ffcb5a1
    \ No newline at end of file
    diff html_no_patch_dot/dir_d44c64559bbebec7f509842c48db8b23.html html_dot/dir_d44c64559bbebec7f509842c48db8b23.html
    8c8
    < <title>cubeb: /tmp/tmp.ilsAtY7fk0/up/cubeb/include Directory Reference</title>
    ---
    > <title>cubeb: include Directory Reference</title>
    Common subdirectories: html_no_patch_dot/search and html_dot/search
    diff html_no_patch_dot/structcubeb__device.html html_dot/structcubeb__device.html
    90c90
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    diff html_no_patch_dot/structcubeb__device__collection.html html_dot/structcubeb__device__collection.html
    100c100
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    diff html_no_patch_dot/structcubeb__device__info.html html_dot/structcubeb__device__info.html
    147c147
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    diff html_no_patch_dot/structcubeb__stream__params.html html_dot/structcubeb__stream__params.html
    167c167
    < <li>/tmp/tmp.ilsAtY7fk0/up/cubeb/include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>
    ---
    > <li>include/cubeb/<a class="el" href="cubeb_8h_source.html">cubeb.h</a></li>

Author: Tachi107

CMakeLists.txt

@@ -366,12 +366,19 @@ endif()
 
 find_package(Doxygen)
 if(DOXYGEN_FOUND)
-  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile @ONLY)
-  add_custom_target(doc ALL
-    ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile
-    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs
-    COMMENT "Generating API documentation with Doxygen" VERBATIM)
-  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs/html/ TYPE DOC)
+  set(DOXYGEN_JAVADOC_AUTOBRIEF YES)
+  set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
+  set(DOXYGEN_CASE_SENSE_NAMES NO)
+  set(DOXYGEN_SORT_MEMBER_DOCS NO)
+  set(DOXYGEN_QUIET YES)
+  set(DOXYGEN_WARN_NO_PARAMDOC YES)
+  set(DOXYGEN_GENERATE_HTML YES)
+
+  doxygen_add_docs(doc "include/cubeb/" ALL
+    COMMENT "Generating API documentation with Doxygen"
+  )
+
+  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ TYPE DOC)
 endif()
 
 if(BUILD_TESTS)