chore: Adding documentation to source.

joakimkarlsson · Jul 18, 2013 · 1e684a7 · 1e684a7
1 parent 0bf87dd
commit 1e684a7
Show file tree

Hide file tree

Showing 5 changed files with 64 additions and 6 deletions.
diff --git a/igloo/core/context.h b/igloo/core/context.h
@@ -12,6 +12,14 @@
 
 namespace igloo {
 
+  //
+  // This class enables us to store attributes with contexts.
+  // Attributes are named string values that can be used for
+  // filtering and reporting etc.
+  //
+  // A testlistener can retrieve the attributes for a context
+  // during a test run.
+  // 
   template <typename ContextType>
     struct ContextAttributeStorage
     {
@@ -35,6 +43,10 @@ namespace igloo {
     };
 
 
+  //
+  // This class is a base class to ContextProvider and adds
+  // the possibility to add attributes to a context.
+  //
   template <typename ContextType>
     struct ContextWithAttribute : ContextBase 
   {

diff --git a/igloo/core/contextbase.h b/igloo/core/contextbase.h
@@ -9,6 +9,9 @@
 
 namespace igloo {
 
+  //
+  // This is the base class for all contexts.
+  // 
   struct ContextBase
   {
     virtual ~ContextBase() {}

diff --git a/igloo/core/contextprovider.h b/igloo/core/contextprovider.h
@@ -73,7 +73,9 @@ namespace igloo {
 
     static bool IsContextMarkedAsOnly()
     {
-      return ISONLY || ContextRegistry<InnerContext>::HasSpecsMarkedAsOnly() || detail::IsContextMarkedAsOnly<OuterContext>();
+      return ISONLY || 
+             ContextRegistry<InnerContext>::HasSpecsMarkedAsOnly() || 
+             detail::IsContextMarkedAsOnly<OuterContext>();
     }
 
     static bool IsMarkedAsSkip()
@@ -151,6 +153,5 @@ namespace igloo {
       }
   };
 
-
 }
 #endif
diff --git a/igloo/core/contextregistry.h b/igloo/core/contextregistry.h
@@ -9,21 +9,48 @@
 
 namespace igloo {
 
+  //
+  // This class stores information about all specs
+  // registered for a context type.
+  //
+  // There are two template types in play here, one at 
+  // the class level, and one for the "Run()" method.
+  //
+  // We separate between 'ContextToCall' and 'ContextToCreate'.
+  // This is used for creating abstract test cases where we
+  // have an abstract base class with test methods (ContextToCall), and
+  // multiple concrete test classes that set up specific versions of 
+  // test environments ('ContextToCreate').
+  //
   template <typename ContextToCall>
   class ContextRegistry  
   {
     typedef void (ContextToCall::*SpecPtr)();
+
+
+    //
+    // Information about a spec.
+    // Contains a pointer to the spec method, plus
+    // information about whether the spec is marked
+    // as "only" or "skip".
+    //
     struct SpecInfo
     {
       SpecPtr spec_ptr;
       bool skip;
       bool only;
     };
+
     typedef std::pair<std::string, SpecInfo> NamedSpec;
     typedef std::map<std::string, SpecInfo> Specs;
 
     public:
-    static void RegisterSpec(const std::string& name, void (ContextToCall::*spec)(), bool skip = false, bool only = false)
+    //
+    // Register a new spec (this is called by the registration
+    // macros during a live run).
+    //
+    static void RegisterSpec(const std::string& name, void (ContextToCall::*spec)(), 
+        bool skip = false, bool only = false)
     {
       SpecInfo spec_info;
       spec_info.spec_ptr = spec;
@@ -38,7 +65,8 @@ namespace igloo {
     }
 
     template <typename ContextToCreate>
-      static void Run(const std::string& contextName, TestResults& results, TestListener& testListener)
+      static void Run(const std::string& contextName, TestResults& results,
+          TestListener& testListener)
       {    
         Specs specs;
         GetSpecsToRun(specs);
@@ -47,7 +75,8 @@ namespace igloo {
 
 
     template <typename ContextToCreate>
-      static void CallSpecs(const Specs& specs, const std::string& contextName, TestResults& results, TestListener& testListener)
+      static void CallSpecs(const Specs& specs, const std::string& contextName,
+          TestResults& results, TestListener& testListener)
       {
         ContextToCreate::SetUpContext();
 
@@ -85,7 +114,8 @@ namespace igloo {
         testListener.ContextRunEnded(c);
       }
 
-    static bool CallSpec(ContextToCall& context, const std::string& specName, SpecPtr spec, TestResults& results)
+    static bool CallSpec(ContextToCall& context, const std::string& specName,
+        SpecPtr spec, TestResults& results)
     {
       bool result = true;
 

diff --git a/igloo/igloo_framework.h b/igloo/igloo_framework.h
@@ -26,7 +26,19 @@ namespace igloo {
 
 #include <igloo/core/core.h>
 
+//
+// These typedefs are used when registering contexts. For root
+// contexts, these are the types available. When a context is
+// registered it will redefine these so that any nested contexts
+// defined within will know about its outer context. We can also
+// use template specialization for contexts with the types here
+// to get different behaviors for root and nested contexts.
+//
 typedef igloo::ContextWithAttribute<void> IGLOO_CURRENT_CONTEXT;
+
+//
+// This is the current root context (void to begin with).
+//
 typedef void IGLOO_ROOT_CONTEXT;