From ffb9e81687cda7a23c4a5cbab1c2b58915b48c09 Mon Sep 17 00:00:00 2001
From: skyjake <skyjake@users.sf.net>
Date: Wed, 6 Mar 2013 21:05:30 +0200
Subject: [PATCH] Documentation|libdeng2: Pimpl macros

---
 doomsday/libdeng2/include/de/libdeng2.h | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/doomsday/libdeng2/include/de/libdeng2.h b/doomsday/libdeng2/include/de/libdeng2.h
index 7445cba451..15bddb9404 100644
--- a/doomsday/libdeng2/include/de/libdeng2.h
+++ b/doomsday/libdeng2/include/de/libdeng2.h
@@ -220,7 +220,11 @@
     private: ClassName(ClassName const &);
 
 /**
- * Macro for starting the definition of a private implementation struct. Example:
+ * Macro for starting the definition of a private implementation struct. The
+ * struct holds a reference to the public instance, which must be specified in
+ * the call to the base class constructor. @see de::Private
+ *
+ * Example:
  * <pre>
  *    DENG2_PIMPL(MyClass)
  *    {
@@ -235,11 +239,18 @@
     typedef ClassName Public; \
     struct ClassName::Instance : public de::Private<ClassName>
 
+/**
+ * Macro for starting the definition of a private implementation struct without
+ * a reference to the public instance. This is useful for simpler classes where
+ * the private implementation mostly holds member variables.
+ */
 #define DENG2_PIMPL_NOREF(ClassName) \
     struct ClassName::Instance : public de::IPrivate
 
 /**
  * Macro for publicly declaring a pointer to the private implementation.
+ * de::PrivateAutoPtr owns the private instance and will automatically delete
+ * it when the PrivateAutoPtr is destroyed.
  */
 #define DENG2_PRIVATE(Var) \
     struct Instance; \
@@ -258,7 +269,7 @@ struct IPrivate {
 #ifdef DENG2_DEBUG
     unsigned int _privateInstVerification;
     IPrivate() : _privateInstVerification(0xdeadbeef) {}
-    unsigned int specialVerification() const { return _privateInstVerification; }
+    unsigned int privateInstVerification() const { return _privateInstVerification; }
 #endif
 };
 
@@ -283,7 +294,7 @@ class PrivateAutoPtr
         IPrivate *ip = reinterpret_cast<IPrivate *>(ptr);
         if(ip)
         {
-            DENG2_ASSERT(ip->specialVerification() == 0xdeadbeef);
+            DENG2_ASSERT(ip->privateInstVerification() == 0xdeadbeef);
             delete ip;
         }
         ptr = p;