Improve Doxygen support

Except Graphviz's `dot` Doxygen may use few other utilities like
`mscgen` (Message Sequence Chart) and `dia` (Diagram Editor).

Now this module allows to manage Doxygen settings from `CMakeLists.txt`
and forget about `Doxyfile`s. Also it provides a helper function
to add a target to generate documentation: `doxygen_add_docs`.

Implement code review notes:

- Introduce `COMPONENTS` to find: `dot`, `mscgen` and `dia`;
- Deprecate variables `DOXYGEN_SKIP_DOT`, `DOXYGEN_EXECUTABLE`,
  `DOXYGEN_DOT_EXECUTABLE`, `DOXYGEN_DOT_FOUND` in favour of
  `doxygen_add_docs ` usage instead;
- Properly handle paths to found tools in Windows;
- Prevent adding a custom target if Doxygen was not really found;
- Introduce exported (executable) targets for found components.

Co-Author: Craig Scott <craig.scott@crascit.com>

Help/release/dev/doxygen-improvements.rst

@@ -0,0 +1,10 @@
+doxygen-improvements
+--------------------
+
+* The :module:`FindDoxygen` module learned to control Doxygen behavior using
+  CMake variables and generate documentation via the newly added
+  :command:`doxygen_add_docs` function. The Doxygen input file (``Doxyfile``)
+  is automatically generated and doxygen is run as part of a custom target.
+  A number of doxygen-related variables have been deprecated. Additional
+  components can be specified to find optional tools: ``dot``, ``mscgen``
+  and ``dia``.

Tests/CMakeLists.txt

@@ -1385,6 +1385,10 @@ ${CMake_BINARY_DIR}/bin/cmake -DDIR=dev -P ${CMake_SOURCE_DIR}/Utilities/Release
     add_subdirectory(FindBZip2)
   endif()
 
+  if(CMake_TEST_FindDoxygen)
+    add_subdirectory(FindDoxygen)
+  endif()
+
   if(CMake_TEST_FindGSL)
     add_subdirectory(FindGSL)
   endif()

Tests/FindDoxygen/CMakeLists.txt

@@ -0,0 +1,20 @@
+add_test(NAME FindDoxygen.SimpleTest COMMAND
+  ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+  --build-and-test
+  "${CMake_SOURCE_DIR}/Tests/FindDoxygen/SimpleTest"
+  "${CMake_BINARY_DIR}/Tests/FindDoxygen/SimpleTest"
+  --build-target allDocTargets
+  ${build_generator_args}
+  --build-options ${build_options}
+)
+
+if(CMake_TEST_FindDoxygen_Dot)
+  add_test(NAME FindDoxygen.DotComponentTest COMMAND
+    ${CMAKE_CTEST_COMMAND} -C $<CONFIGURATION>
+    --build-and-test
+    "${CMake_SOURCE_DIR}/Tests/FindDoxygen/DotComponentTestTest"
+    "${CMake_BINARY_DIR}/Tests/FindDoxygen/DotComponentTestTest"
+    ${build_generator_args}
+    --build-options ${build_options}
+  )
+endif()

Tests/FindDoxygen/DotComponentTestTest/CMakeLists.txt

@@ -0,0 +1,18 @@
+cmake_minimum_required(VERSION 3.8)
+project(TestFindDoxygenDot VERSION 1.0 LANGUAGES NONE)
+
+# Testing a new signature w/ components
+find_package(Doxygen REQUIRED COMPONENTS dot)
+
+# No backwards compatibility expected when component form is used
+if(TARGET Doxygen::doxygen)
+    if(DOXYGEN)
+        message(FATAL_ERROR "DOXYGEN unexpectedly defined with component form")
+    endif()
+else()
+    message(FATAL_ERROR "Import target Doxygen::doxygen not defined")
+endif()
+
+if(NOT TARGET Doxygen::dot)
+    message(FATAL_ERROR "Import target Doxygen::dot not defined")
+endif()

Tests/FindDoxygen/SimpleTest/CMakeLists.txt

@@ -0,0 +1,59 @@
+cmake_minimum_required(VERSION 3.8)
+project(TestFindDoxygen VERSION 1.0 LANGUAGES NONE)
+
+# Testing backward compatible signature
+find_package(Doxygen REQUIRED)
+
+if(TARGET Doxygen::doxygen)
+    # Check backward compatibility
+    if(NOT DOXYGEN_EXECUTABLE)
+        message(FATAL_ERROR "Backward compatibility broken: DOXYGEN_EXECUTABLE not set")
+    endif()
+    if(NOT DOXYGEN)
+        message(FATAL_ERROR "Backward compatibility broken: DOXYGEN not set")
+    endif()
+    # Check presence of expected generated files
+    foreach(file CMakeDoxyfile.in CMakeDoxygenDefaults.cmake)
+        if(NOT EXISTS "${PROJECT_BINARY_DIR}/${file}")
+            message(FATAL_ERROR "Missing generated file: ${file}")
+        endif()
+    endforeach()
+else()
+    message(FATAL_ERROR "Import target Doxygen::doxygen not defined")
+endif()
+
+doxygen_add_docs(docsNoArgs)
+if(NOT EXISTS "${PROJECT_BINARY_DIR}/Doxyfile.docsNoArgs")
+    message(FATAL_ERROR "Missing generated file: Doxyfile.docsNoArgs")
+endif()
+if(NOT TARGET docsNoArgs)
+    message(FATAL_ERROR "Target docsNoArgs not created")
+endif()
+
+configure_file(spaces_in_name.cpp.in "spaces in name.cpp" COPYONLY)
+doxygen_add_docs(docsWithArgs
+    "${CMAKE_CURRENT_BINARY_DIR}/spaces in name.cpp"
+    main.cpp
+)
+if(NOT EXISTS "${PROJECT_BINARY_DIR}/Doxyfile.docsWithArgs")
+    message(FATAL_ERROR "Missing generated file: Doxyfile.docsWithArgs")
+endif()
+if(NOT TARGET docsWithArgs)
+    message(FATAL_ERROR "Target docsWithArgs not created")
+endif()
+# Note that CMake inserts at least one entry into SOURCES when a COMMAND or
+# DEPENDS option is given to add_custom_target(), so rather than looking for an
+# exact match, we only verify that the files we expect to be there are present
+get_target_property(srcList docsWithArgs SOURCES)
+set(expectedList
+    "${CMAKE_CURRENT_BINARY_DIR}/spaces in name.cpp"
+    "${CMAKE_CURRENT_SOURCE_DIR}/main.cpp"
+)
+foreach(f IN LISTS expectedList)
+    if(NOT f IN_LIST srcList)
+        message(FATAL_ERROR "SOURCES missing file: ${f}")
+    endif()
+endforeach()
+
+add_custom_target(allDocTargets)
+add_dependencies(allDocTargets docsNoArgs docsWithArgs)

Tests/FindDoxygen/SimpleTest/main.cpp

@@ -0,0 +1,4 @@
+/**
+ * \file
+ * \brief One C++ file w/ sample Doxygen comment just to produce any docs...
+ */

Tests/FindDoxygen/SimpleTest/spaces_in_name.cpp.in

@@ -0,0 +1,4 @@
+/**
+ * \file
+ * \brief This file name contains spaces
+ */