From df6621f2b54aa488468ac64f6147572cb1f50eb4 Mon Sep 17 00:00:00 2001
From: Christian Gruber <christian.gruber@posteo.de>
Date: Fri, 10 Jul 2020 23:50:10 +0200
Subject: [PATCH] Add doxygen documentation to QofFakeQuery and
 QofFakeQueryPool

---
 libgnucash/engine/mocks/fake-qofquery.cpp | 12 ++++++
 libgnucash/engine/mocks/fake-qofquery.h   | 46 ++++++++++++++++++++++-
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/libgnucash/engine/mocks/fake-qofquery.cpp b/libgnucash/engine/mocks/fake-qofquery.cpp
index a6479040c8..d8eca210a7 100644
--- a/libgnucash/engine/mocks/fake-qofquery.cpp
+++ b/libgnucash/engine/mocks/fake-qofquery.cpp
@@ -1,3 +1,7 @@
+/**
+ * @file fake-qofquery.cpp
+*/
+
 #include <config.h>
 
 #include <list>
@@ -12,11 +16,14 @@
 static class QofFakeQueryPool
 {
 public:
+
+    /* Add QofFakeQuery object to the pool */
     void add_query(QofFakeQuery *query)
     {
         m_queriesNew.push_back(query);
     }
 
+    /* Request to use a QofFakeQuery object */
     QofFakeQuery* request_query(QofIdTypeConst obj_type)
     {
         QofFakeQuery* query = nullptr;
@@ -36,6 +43,8 @@ public:
         return query;
     }
 
+    /* Check if a QofFakeQuery object is currently used, i.e. it has been
+     * requested before */
     bool query_used(QofQuery *query)
     {
         auto it = std::find(m_queriesUsed.begin(), m_queriesUsed.end(), (QofFakeQuery*)query);
@@ -43,6 +52,8 @@ public:
         return (it != m_queriesUsed.end());
     }
 
+    /* Release a formerly requested QofFakeQuery object, which is not used
+     * anymore */
     void release_query(QofFakeQuery *query)
     {
         ASSERT_TRUE(query_used((QofQuery*)query));
@@ -51,6 +62,7 @@ public:
         m_queriesConsumed.push_back(*it);
     }
 
+    /* Remove a formerly added QofFakeQueryObject from the pool */
     void remove_query(QofFakeQuery *query)
     {
         ASSERT_FALSE(query_used((QofQuery*)query));
diff --git a/libgnucash/engine/mocks/fake-qofquery.h b/libgnucash/engine/mocks/fake-qofquery.h
index 13a5df2bd6..803f56dbd6 100644
--- a/libgnucash/engine/mocks/fake-qofquery.h
+++ b/libgnucash/engine/mocks/fake-qofquery.h
@@ -1,3 +1,9 @@
+/**
+ * @file fake-qofquery.h
+ *
+ * @brief Mocking qof queries
+*/
+
 #ifndef FAKE_QOFQUERY_H
 #define FAKE_QOFQUERY_H
 
@@ -10,8 +16,44 @@ extern "C"
 #include <Query.h>
 }
 
-// Fake object providing functionality similar to QofQuery
-// Note: QofQuery is a typedef for struct _QofQuery, which is is not public
+/** Fake object providing functionality similar to QofQuery
+ *
+ * @note QofQuery is a @c typedef for @c struct _QofQuery, which is not
+ * public. Therefore class QofFakeQuery is not derived from QofQuery.
+ *
+ * To use a QofFakeQuery object simply create it before the GnuCash code
+ * performs a query. Check that the QofFakeQuery object is created with the
+ * correct object type. Also define all expectations and return values on the
+ * created QofFakeQuery object before the GnuCash code performs the query.
+ *
+ * After the query is finished, the QofFakeQuery object can be destroyed. A
+ * QofFakeQuery object can only be used once.
+ *
+ * Internally each created QofFakeQuery object is registered at a
+ * QofFakeQueryPool, which provides it to the GnuCash code on request. This
+ * pool observes the life-cycle of each QofFakeQuery object. The following
+ * steps are expected to be done on each QofFakeQuery object in the
+ * specified order:
+ *    -# create QofFakeQuery object (test application)
+ *    -# call qof_query_create_for() (GnuCash code)
+ *    -# call qof_query_run() (GnuCash code)
+ *    -# call qof_query_destroy() (GnuCash code)
+ *    -# destroy QofFakeQuery object (test application)
+ *
+ * The calls to qof_query_create_for(), qof_query_run() and qof_query_destroy()
+ * are optional, but
+ *    -  qof_query_create_for() and qof_query_destroy() have to be called in
+ *       pairs
+ *    -  if qof_query_run() is called, qof_query_create_for() has to be called
+ *       before as well
+ *
+ * Several GTest assertions are implemented to signal violations of the
+ * QofFakeQuery object life-cycle.
+ *
+ * @note If you want to check, that a certain query is run by the GnuCash code,
+ * then define the appropriate expectations on the QofFakeQuery object in your
+ * test application.
+ */
 class QofFakeQuery
 {
 public: