From 4c51fcada1d6483392c52a3d8a5a34cc9944e828 Mon Sep 17 00:00:00 2001
From: Mike Bierlee <m.bierlee@lostmoment.com>
Date: Sun, 15 Feb 2015 16:52:03 +0100
Subject: [PATCH] Document public API of module "autowire"

---
 source/poodinis/autowire.d | 66 +++++++++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 4 deletions(-)

diff --git a/source/poodinis/autowire.d b/source/poodinis/autowire.d
index f8b2ce7..e9a4ac1 100644
--- a/source/poodinis/autowire.d
+++ b/source/poodinis/autowire.d
@@ -1,8 +1,16 @@
 /**
- * Poodinis Dependency Injection Framework
- * Copyright 2014-2015 Mike Bierlee
- * This software is licensed under the terms of the MIT license.
- * The full terms of the license can be found in the LICENSE file.
+ * Contains functionality for autowiring dependencies using a dependency container.
+ *
+ * This module is used in a dependency container for autowiring dependencies when resolving them.
+ * You typically only need this module if you want inject dependencies into a class instance not
+ * managed by a dependency container.
+ *
+ * Authors:
+ *  Mike Bierlee, m.bierlee@lostmoment.com
+ * Copyright: 2014-2015 Mike Bierlee
+ * License:
+ *  This software is licensed under the terms of the MIT license.
+ *  The full terms of the license can be found in the LICENSE file.
  */
 
 module poodinis.autowire;
@@ -19,12 +27,57 @@ debug {
 
 struct UseMemberType {};
 
+/**
+ * UDA for annotating class members as candidates for autowiring.
+ *
+ * Annotate member declarations in classes with this UDA to make them eligable for autowiring.
+ *
+ * Optionally a type as template parameter can be suplied to specify a qualifier. Qualifiers are used
+ * to autowire members according the the type given. If class X, which inherits class Y, is given a qualifier
+ * of type Y, then only class X's members inherited from type Y are autowired. If no qualifier is supplied, the
+ * type of the member is used as qualifier.
+ *
+ * Examples:
+ * Annotate member of class to be autowired:
+ * ---
+ * class Car {
+ *    @Autowire
+ *    public Engine engine;
+ * }
+ * ---
+ *
+ * Annotate member of class with qualifier:
+ * ---
+ * class V8Engine : Engine { ... }
+ *
+ * class Car {
+ *    @Autowire!V8Engine
+ *    public Engine engine;
+ * }
+ * ---
+ * The members of member "engine" will now be autowired properly, because the autowire mechanism will
+ * autowire member "engine" as if it's of type "V8Engine".
+ */
 struct Autowire(QualifierType = UseMemberType) {
 	QualifierType qualifier;
 };
 
+/**
+ * Alias to "Autowire" UDA for those used to Spring.
+ */
 alias Autowired = Autowire;
 
+/**
+ * Autowires members of a given instance using dependencies registered in the given container.
+ *
+ * All public members of the given instance, which are annotated using the "Autowire" UDA, are autowired.
+ * All members are resolved using the given container. Qualifiers are used to determine the type of class to
+ * resolve for any member of instance.
+ *
+ * Note that private members will not be autowired.
+ *
+ * See_Also: Autowire
+ */
 public void autowire(Type)(DependencyContainer container, Type instance) {
 	// For the love of god, refactor this!
 
@@ -72,6 +125,11 @@ public void autowire(Type)(DependencyContainer container, Type instance) {
 	}
 }
 
+/**
+ * Autowire the given instance using the global dependency container.
+ *
+ * See_Also: DependencyContainer
+ */
 public void globalAutowire(Type)(Type instance) {
 	DependencyContainer.getInstance().autowire(instance);
 }