fix: Fix Doxygen warnings from README

Since the inception of the project, we have used the repository’s README
as the main page for our generated Doxygen documentation.  Doxygen
doesn’t understand the HTML we use in our README, though, so it
generates warnings on every build.

This patch adds a very simple main page to our Doxygen documentation,
written in Doxygen’s native format (a file with the extension `.dox`
that contains a Doxygen-style C++ comment).  This new main page replaces
our README only in the generated API documentation, not on our GitHub
repo.  After applying this patch, there should be no warnings when
generating our API documentation.

Signed-off-by: Patrick M. Niedzielski <[email protected]>

Author: pniedzielski

CMakeLists.txt

@@ -266,7 +266,6 @@ if(DOXYGEN_FOUND)
   set(DOXYGEN_PROJECT_BRIEF
     "C++ SDK for BlazingMQ clients and plugins"
   )
-  set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ./README.md)
   set(DOXYGEN_REFERENCED_BY_RELATION YES)
   set(DOXYGEN_REFERENCES             YES)
   set(DOXYGEN_ALPHABETICAL_INDEX     NO)
@@ -277,10 +276,10 @@ if(DOXYGEN_FOUND)
   )
   doxygen_add_docs(
     apidocs
+    docs/mainpage.dox
     src/groups/bmq/bmqa
     src/groups/bmq/bmqt
     src/groups/bmq/bmqpi
-    README.md
     COMMENT "Generate public Doxygen documentation for libbmq"
   )
   add_dependencies(docs apidocs)

docs/mainpage.dox

@@ -0,0 +1,31 @@
+/**
+
+\mainpage BlazingMQ C++ SDK API Documentation
+
+\image html blazingmq_logo_label.svg width=50%
+
+[BlazingMQ](https://bloomberg.github.io/blazingmq) is an open source
+distributed message queueing framework, which focuses on efficiency,
+reliability, and a rich feature set for modern-day workflows.
+
+At its core, BlazingMQ provides durable, fault-tolerant, highly performant, and
+highly available queues, along with features like various message routing
+strategies (e.g., work queues, priority, fan-out, broadcast, etc.),
+compression, strong consistency, poison pill detection, etc.
+
+These pages are the API documentation for the BlazingMQ C++ SDK for client
+applications and plugins.
+
+\section mainpage-license License
+
+The BlazingMQ C++ SDK and documentation are Apache 2.0 licensed.
+
+\section mainpage-quickstart Quickstart
+
+Authors of client application should look in the \ref src/groups/bmq/bmqa "bmqa"
+package for an API with which to build producers and consumers.
+
+Plugin authors should look in the \ref src/groups/bmq/bmqpi "bmqpi" package for
+the pure abstract interfaces which broker plugins need to implement.
+
+*/