From 46f7b76e30c98ec2e667b86786278932e41ea29c Mon Sep 17 00:00:00 2001
From: "Patrick M. Niedzielski" <patrick@pniedzielski.net>
Date: Mon, 7 Oct 2024 10:57:46 -0400
Subject: [PATCH] Docs[BMQ]: Use `.dox` files rather than `.md` files

Package group documentation in `libbmq` was converted to Markdown files
named `README.md`, and which was tied to the directory containing the
code for the package group using Doxygen `@dir` commands.  However, when
generating the documentation, this left several empty pages in the
documentation named `README`, which we were not able to remove.

The solution for this that this patch uses is to switch from `.md` files
to `.dox` files, which contain a single Doxygen-style C++ comment
containing the `@dir` command.  Unlike `.md` files, these do not
automatically create pages, so there is no empty `README` page created
for each package group.  The cost of this is that `.dox` files cannot be
simple Markdown files, but instead need to be wrapped in a C++ comment.

Signed-off-by: Patrick M. Niedzielski <patrick@pniedzielski.net>
---
 Doxyfile                                       | 3 ++-
 src/groups/bmq/bmqa/{README.md => README.dox}  | 2 ++
 src/groups/bmq/bmqpi/{README.md => README.dox} | 2 ++
 src/groups/bmq/bmqt/{README.md => README.dox}  | 2 ++
 4 files changed, 8 insertions(+), 1 deletion(-)
 rename src/groups/bmq/bmqa/{README.md => README.dox} (96%)
 rename src/groups/bmq/bmqpi/{README.md => README.dox} (98%)
 rename src/groups/bmq/bmqt/{README.md => README.dox} (96%)

diff --git a/Doxyfile b/Doxyfile
index f63649e2e..353c6e02b 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -989,7 +989,8 @@ INPUT_FILE_ENCODING    =
 FILE_PATTERNS          = *.c \
                          *.cpp \
                          *.h \
-                         *.md
+                         *.md \
+                         *.dox
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
diff --git a/src/groups/bmq/bmqa/README.md b/src/groups/bmq/bmqa/README.dox
similarity index 96%
rename from src/groups/bmq/bmqa/README.md
rename to src/groups/bmq/bmqa/README.dox
index 5dfe3dfa7..f5bd5ad46 100644
--- a/src/groups/bmq/bmqa/README.md
+++ b/src/groups/bmq/bmqa/README.dox
@@ -1,6 +1,8 @@
+/**
 @dir bmqa
 
 @brief The `BMQA` (BlazingMQ API) package provides applications a public API
 
 The `bmqa` package provides the public API of the BlazingMQ SDK for
 applications to use.
+*/
diff --git a/src/groups/bmq/bmqpi/README.md b/src/groups/bmq/bmqpi/README.dox
similarity index 98%
rename from src/groups/bmq/bmqpi/README.md
rename to src/groups/bmq/bmqpi/README.dox
index 35ea63ab5..df13d9cb9 100644
--- a/src/groups/bmq/bmqpi/README.md
+++ b/src/groups/bmq/bmqpi/README.dox
@@ -1,3 +1,4 @@
+/**
 @dir bmqpi
 
 @brief The `BMQPI` (BlazingMQ Public Interfaces) package provides class
@@ -8,3 +9,4 @@ clients to extend in their own applications and libraries. These extension
 points facilitate integration with other aspects of a runtime environment (e.g.
 authentication, host health-checking), which may vary significantly from
 organization to organization.
+*/
diff --git a/src/groups/bmq/bmqt/README.md b/src/groups/bmq/bmqt/README.dox
similarity index 96%
rename from src/groups/bmq/bmqt/README.md
rename to src/groups/bmq/bmqt/README.dox
index 33ce546b2..3c88e8cbd 100644
--- a/src/groups/bmq/bmqt/README.md
+++ b/src/groups/bmq/bmqt/README.dox
@@ -1,3 +1,4 @@
+/**
 @dir bmqt
 
 @brief The `BMQT` (BlazingMQ (vocabulary) Types) package provides
@@ -5,3 +6,4 @@ value-semantic vocabulary types.
 
 The ‘bmqt‘ package provides low level value-semantic vocabulary types for use
 by the BlazingMQ SDK.
+*/