README with some comments in the code added

Author: vblosh

README.md

@@ -0,0 +1,109 @@
+# About
+
+*DIContainerCpp* is a simple but powerful dependency-injection container for C++.
+
+# Usage
+
+DIContainerCpp is inspired by Microsoft's COM object model.
+Every interface managed by with library must implement `IUnknown`, and have a unique ID in additon to that.
+
+## Writing components
+
+```c++
+using UID = long;
+
+const UID IUnknown = 1;
+
+struct IUnknown
+{
+	virtual unsigned int AddRef() = 0; // Increase the interface's RefCount
+	virtual unsigned int Release() = 0; // Decrease the interface's RefCount. If zero, the component must be free itself.
+	virtual IUnknown* QueryInterface(UID id) = 0; // Return the implementation of the interface known by `id`.
+};
+```
+
+Every component is a collection of one-or-more interfaces and must implement `IComponent` (which in-turn derives from `IUnknown`):
+
+```c++
+struct IComponent : IUnknown
+{
+	// Return a list of interfaces that this component requires
+	virtual std::vector<UID>& GetDependencies() = 0;
+	// Inject the interface `dependency` with `id` into this component.
+	// `id` will have been returned by `GetDependencies()`
+	virtual void SetDependency(UID id, IUnknown* dependency) = 0;
+};
+```
+
+## Using the container
+
+The container itself, `DIContainer`, implements `IContainer`:
+
+```c++
+struct IContainer
+{
+	// Return the registered interface by `id`
+	virtual IUnknown* GetInterface(UID id) = 0;
+};
+
+enum class CreationPolicy
+{
+	NewInstance, // New instance for every GetInterface() call
+	SharedInstance // One instance per container
+};
+
+// E.g. []()->IComponent* { return new MyFancyCustomComponent(); }
+typedef IComponent* (*CreateInstanceFunc)(void);
+
+class DIContainer : IContainer {
+public:
+	// Register a component with the unique `id` to be lazily created using a `createFn` and a creation `policy`
+	void RegisterInterface(UID id, CreateInstanceFunc createFn, CreationPolicy policy=CreationPolicy::NewInstance);
+	virtual IUnknown* GetInterface(UID id) override;
+}
+```
+
+Note that cyclic dependencies are detected automatically and raise a `DIContainerException`.
+
+Example of using a DIContainer.
+
+```c++
+	// Container initialization
+    DIContainer cont;
+    // Register components in the container
+    try {
+        cont.RegisterInterface(UIDComponent3, []()->IComponent* { return new Component3; });
+        cont.RegisterInterface(UIDComponent4, []()->IComponent* { return new Component4; });
+    }
+    catch (const DIContainerExeption& ex) {
+    }
+
+    // using components
+    ComPtr<IComponent1, UIDComponent1> cmp1(cont.GetInterface(UIDComponent1));
+    int res1 = cmp1->Calculate(val);
+
+    ComPtr<IComponent2, UIDComponent2> cmp2 = (IComponent2*)cont.GetInterface(UIDComponent2);
+    int res2 = cmp2->Calculate(val);
+```
+
+See [tests/](tests/) for more examples.
+
+# Hacking
+
+## Building
+
+This project uses the CMake build-system. To build it, simply run the following commands:
+
+```console
+$ mkdir build
+$ cd build/
+$ cmake ..
+$ make
+```
+
+## Running tests
+
+This project uses *GoogleTest*.
+
+1. Build the project
+2. `cd build/ && ./runUnitTests`

src/DIContainer.h

@@ -12,6 +12,7 @@ enum class CreationPolicy
 	SharedInstance
 };
 
+// E.g. []()->IComponent* { return new MyFancyCustomComponent(); }
 typedef IComponent* (*CreateInstanceFunc)(void);
 
 class DIContainerExeption : public std::runtime_error
@@ -27,9 +28,11 @@ class DIContainer : public IContainer
 public:
 	DIContainer();
 	~DIContainer();
-
-	// IContainer implementation
+	
+	// Register a component with the unique `id` to be lazily created using a `createFn` and a creation `policy`
 	void RegisterInterface(UID id, CreateInstanceFunc createFn, CreationPolicy policy=CreationPolicy::NewInstance);
+	
+	// IContainer implementation
 	virtual IUnknown* GetInterface(UID id) override;
 
 private:

src/IComponent.h

@@ -6,6 +6,9 @@ const UID UIDIComponent = 1;
 
 struct IComponent : IUnknown
 {
+	// Return a list of interfaces that this component requires
 	virtual std::vector<UID>& GetDependencies() = 0;
+	// Inject the interface `dependency` with `id` into this component.
+	// `id` will have been returned by `GetDependencies()`
 	virtual void SetDependency(UID id, IUnknown* dependency) = 0;
 };

src/IContainer.h

@@ -3,5 +3,6 @@
 
 struct IContainer
 {
+	// Return the registered in the DIContainer interface by `id`
 	virtual IUnknown* GetInterface(UID id) = 0;
 };

src/IUnknown.h

@@ -5,9 +5,10 @@ using UID = long;
 
 const UID UIDIUnknown = 1;
 
+// `IUnknown` is the base for all interfaces managed with this library
 struct IUnknown
 {
-	virtual unsigned int AddRef() = 0;
-	virtual unsigned int Release() = 0;
-	virtual IUnknown* QueryInterface(UID id) = 0;
-};
+	virtual unsigned int AddRef() = 0; // Increase the interface's RefCount
+	virtual unsigned int Release() = 0; // Decrease the interface's RefCount. If zero, the component must be free itself.
+	virtual IUnknown* QueryInterface(UID id) = 0; // Return the implementation of the interface known by `id`.
+};

tests/DIContainerTests.cpp

@@ -3,6 +3,8 @@
 #include <string>
 
 #include "../src/DIContainer.h"
+#include "../src/ComPtr.h"
+
 #include "component1.h"
 #include "component2.h"
 #include "component3.h"
@@ -12,7 +14,39 @@ IComponent* CreateCmp1() {
     return new Component1;
 }
 
-TEST(DIContainer, TEST1) {
+TEST(DIContainer, ComPtr) {
+    DIContainer cont;
+    // Register components in the container
+    cont.RegisterInterface(UIDComponent1, CreateCmp1, CreationPolicy::SharedInstance);
+    cont.RegisterInterface(UIDComponent2, []()->IComponent* { return new Component2; });
+
+    int val = 12;
+    ComPtr<IComponent1, UIDComponent1> cmp1(cont.GetInterface(UIDComponent1));
+    int res1 = cmp1->Calculate(val);
+    EXPECT_EQ(res1, val * val);
+
+    ComPtr<IComponent2, UIDComponent2> cmp2 = (IComponent2*)cont.GetInterface(UIDComponent2);
+    int res2 = cmp2->Calculate(val);
+    EXPECT_EQ(res2, val * val * 2);
+}
+
+TEST(DIContainer, ComPtrUsage) {
+    DIContainer cont;
+    cont.RegisterInterface(UIDComponent1, CreateCmp1, CreationPolicy::SharedInstance);
+    cont.RegisterInterface(UIDComponent2, []()->IComponent* { return new Component2; });
+
+    int val = 12;
+    IComponent1* cmp1 = (IComponent1*)cont.GetInterface(UIDComponent1);
+    int res1 = cmp1->Calculate(val);
+    EXPECT_EQ(res1, val * val);
+
+    IComponent2* cmp2 = (IComponent2*)cont.GetInterface(UIDComponent2);
+    int res2 = cmp2->Calculate(val);
+    EXPECT_EQ(res2, val * val * 2);
+}
+
+
+TEST(DIContainer, AddRefRelease) {
     DIContainer cont;
     cont.RegisterInterface(UIDComponent1, CreateCmp1, CreationPolicy::SharedInstance);
     cont.RegisterInterface(UIDComponent2, []()->IComponent* { return new Component2; });