Update header guards for `assert_test.h` and `assert_debug.h`

- Introduce distinct header guards to enable simultaneous inclusion of both headers. - Update `README-maintainer.md` to document the changes .

Update header guards for `assert_test.h` and `assert_debug.h`
- Introduce distinct header guards to enable simultaneous inclusion of both headers. - Update `README-maintainer.md` to document the changes .
m-holger
1 parent 3a9ec47d
Showing 3 changed files with 26 additions and 30 deletions
README-maintainer.md
libqpdf/qpdf/assert_debug.h
libqpdf/qpdf/assert_test.h
@@ -219,13 +219,19 @@ Building docs from pull requests is also enabled.
   serves to
   * remind us that assert in release code disappears and so should only
-    be used for debugging; when doing so use a Debug build
-    configuration
+    be used to document pre/post conditions and invariants, and for
+    sanity checks during development and testing; when doing so use
+    a Debug build configuration.
   * protect us from using assert in test code without explicitly
     removing the NDEBUG definition, since that would cause the assert
     not to actually be testing anything in non-Debug build
     configurations.
+  
+  Prior to 12.3 assert_test.h and assert_debug.h shared the same header
+  guard, which prevented the simultaneous inclusion of both headers.
+  This was changed to permit the CI testing of private-API methods
+  without loosing the use of assertions in private header files.
 * In a source file, include the header file that declares the source
   class first followed by a blank line. If a config file is needed
@@ -4,23 +4,18 @@
  * disabled in release code. Use qpdf_assert_debug in the code.
  */
-/* assert_debug and assert_test intentionally use the same
- * guard. Search for assert in README-MAINTAINER.
- */
-#ifdef QPDF_ASSERT_H
-# error "At most one qpdf/assert header may be included at most one time"
-#else
-# define QPDF_ASSERT_H
+#ifndef QPDF_ASSERT_DEBUG_H
+#define QPDF_ASSERT_DEBUG_H
-# include <cassert>
-# define qpdf_assert_debug assert
+#include <cassert>
+#define qpdf_assert_debug assert
 // Alias for assert. Pre-condition is only enforced in debug builds.
-# define qpdf_expect assert
+#define qpdf_expect assert
 // Alias for assert. Post-condition is only enforced in debug builds.
-# define qpdf_ensures assert
+#define qpdf_ensures assert
 // Alias for assert. Invariant is only enforced in debug builds.
-# define qpdf_invariant assert
+#define qpdf_invariant assert
 // Alias for static_assert.
-# define qpdf_static_expect static_assert
+#define qpdf_static_expect static_assert
-#endif /* QPDF_ASSERT_H */
+#endif /* QPDF_ASSERT_DEBUG_H */
 /*
- * Include this file to use assert in regular code for
- * debugging/strong sanity checking, knowing that the assert will be
- * disabled in release code. Use qpdf_debug_assert in the code.
+ * Include this file to use assert in CI code for. This will allow
+ * the use of assert and ensure that NDEBUG is undefined (which
+ * would cause spurious CI passes).
  */
-/* assert_debug and assert_test intentionally use the same
- * guard. Search for assert in README-MAINTAINER.
- */
-#ifdef QPDF_ASSERT_H
-# error "At most one qpdf/assert header may be included at most one time"
-#else
-# define QPDF_ASSERT_H
+#ifndef QPDF_ASSERT_TEST_H
+#define QPDF_ASSERT_TEST_H
-# ifdef NDEBUG
-#  undef NDEBUG
-# endif
-# include <assert.h>
+#ifdef NDEBUG
+# undef NDEBUG
+#endif
+#include <assert.h>
 #endif /* QPDF_ASSERT_H */