API docs polishing (alanxz#37 reworked and expanded)

- Main Page is not blank now, but displays README.md
  // see recipe by the Doxygen author: https://stackoverflow.com/a/13442157/531179
  // the USE_MDFILE_AS_MAINPAGE option available since Doxygen 1.8.3 (2012)

- @file briefs added for pretty File List

- SVG dot graphs enabled in the Doxyfile

- clang-format rerun to produce aligned doc comment blocks

- misc typos caught and eliminated

- missing coverage expanded by citing the AMQP 0.9.1 spec

- `@param [in/out] foobar` syntax fixed

- brief line/details separation fixed

- "Defaults to xxx" remarks mostly removed, as this just duplicates information
  from the function signature

CMakeLists.txt

@@ -169,11 +169,24 @@ endif (ENABLE_TESTING)
 
 
 # Documentation generation
-set(DOXYFILE_LATEX "NO")
-set(PROJECT_VERSION ${SAC_VERSION})
-include(UseDoxygen)
+find_package(Doxygen COMPONENTS dot)
+option(BUILD_API_DOCS "Build Doxygen API docs" ${DOXYGEN_FOUND})
 
-include(GNUInstallDirs)
+if (BUILD_API_DOCS)
+  if (NOT DOXYGEN_FOUND)
+    message(FATAL_ERROR "Doxygen is required to build the API documentation")
+  endif ()
+  configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/docs/Doxyfile @ONLY)
+
+  add_custom_target(docs ALL
+    COMMAND ${DOXYGEN_EXECUTABLE}
+    VERBATIM
+    WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs
+    DEPENDS SimpleAmqpClient
+    COMMENT "Generating API documentation"
+    SOURCES ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
+    )
+endif ()
 
 install(TARGETS SimpleAmqpClient
     RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}