Skip to content
Browse files

Added AsDoc comments for lots of methods in Injector and some other c…

…lasses
  • Loading branch information...
1 parent 6d44ee7 commit 21051a066f03ac1db99a58c2438c9a2982ff48e6 @tschneidereit committed Oct 27, 2011
Showing with 144 additions and 55 deletions.
  1. +10 −0 src/avmplus/DescribeTypeJSON.as
  2. +134 −52 src/org/swiftsuspenders/Injector.as
  3. +0 −3 src/org/swiftsuspenders/MappingEvent.as
View
10 src/avmplus/DescribeTypeJSON.as
@@ -7,6 +7,16 @@
package avmplus
{
+ /**
+ * Makes the hidden, inofficial function describeTypeJSON available outside of the avmplus
+ * package.
+ *
+ * <strong>As Adobe doen't officially support this method and it is only visible to client
+ * code by accident, it should only ever be used with runtime-detection and automatic fallback
+ * on describeType.</strong>
+ *
+ * @see http://www.tillschneidereit.de/2009/11/22/improved-reflection-support-in-flash-player-10-1/
+ */
public class DescribeTypeJSON
{
//---------------------- Public Properties ----------------------//
View
186 src/org/swiftsuspenders/Injector.as
@@ -26,119 +26,122 @@ package org.swiftsuspenders
/**
* This event is dispatched each time the injector instantiated a class
*
- * At the point where the event is dispatched none of the injection points have been processed.
+ * <p>At the point where the event is dispatched none of the injection points have been processed.</p>
*
- * The only difference to the <code>PRE_CONSTRUCT</code> event is that
+ * <p>The only difference to the <code>PRE_CONSTRUCT</code> event is that
* <code>POST_INSTANTIATE</code> is only dispatched for instances that are created in the
* injector, whereas <code>PRE_CONSTRUCT</code> is also dispatched for instances the injector
- * only injects into.
+ * only injects into.</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.InjectionEvent
+ * @eventType org.swiftsuspenders.InjectionEvent.POST_INSTANTIATE
*/
[Event(name='postInstantiate', type='org.swiftsuspenders.InjectionEvent')]
/**
* This event is dispatched each time the injector is about to inject into a class
*
- * At the point where the event is dispatched none of the injection points have been processed.
+ * <p>At the point where the event is dispatched none of the injection points have been processed.</p>
*
- * The only difference to the <code>POST_INSTANTIATE</code> event is that
+ * <p>The only difference to the <code>POST_INSTANTIATE</code> event is that
* <code>PRE_CONSTRUCT</code> is only dispatched for instances that are created in the
* injector, whereas <code>POST_INSTANTIATE</code> is also dispatched for instances the
- * injector only injects into.
+ * injector only injects into.</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.InjectionEvent
+ * @eventType org.swiftsuspenders.InjectionEvent.PRE_CONSTRUCT
*/
[Event(name='preConstruct', type='org.swiftsuspenders.InjectionEvent')]
/**
* This event is dispatched each time the injector created and fully initialized a new instance
*
- * At the point where the event is dispatched all dependencies for the newly created instance
+ * <p>At the point where the event is dispatched all dependencies for the newly created instance
* have already been injected. That means that creation-events for leaf nodes of the created
* object graph will be dispatched before the creation-events for the branches they are
- * injected into.
+ * injected into.</p>
*
- * The newly created instance's [PostConstruct]-annotated methods will also have run already.
+ * <p>The newly created instance's [PostConstruct]-annotated methods will also have run already.</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.InjectionEvent
+ * @eventType org.swiftsuspenders.InjectionEvent.POST_CONSTRUCT
*/
[Event(name='postConstruct', type='org.swiftsuspenders.InjectionEvent')]
/**
* This event is dispatched each time the injector creates a new mapping for a type/ name
* combination, right before the mapping is created
*
- * At the point where the event is dispatched the mapping hasn't yet been created. Thus, the
- * respective field in the event is null.
+ * <p>At the point where the event is dispatched the mapping hasn't yet been created. Thus, the
+ * respective field in the event is null.</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.MappingEvent
+ * @eventType org.swiftsuspenders.MappingEvent.PRE_MAPPING_CREATE
*/
[Event(name='preMappingCreate', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time the injector creates a new mapping for a type/ name
* combination, right after the mapping was created
*
- * At the point where the event is dispatched the mapping has already been created and stored
- * in the injector's lookup table.
+ * <p>At the point where the event is dispatched the mapping has already been created and stored
+ * in the injector's lookup table.</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.MappingEvent
+ * @eventType org.swiftsuspenders.MappingEvent.POST_MAPPING_CREATE
*/
[Event(name='postMappingCreate', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time an injector mapping is changed in any way, right before
* the change is applied.
*
- * At the point where the event is dispatched the changes haven't yet been applied, meaning the
- * mapping stored in the event can be queried for its pre-change state
+ * <p>At the point where the event is dispatched the changes haven't yet been applied, meaning the
+ * mapping stored in the event can be queried for its pre-change state.</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.MappingEvent
+ * @eventType org.swiftsuspenders.MappingEvent.PRE_MAPPING_CHANGE
*/
[Event(name='preMappingChange', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time an injector mapping is changed in any way, right after
* the change is applied.
*
- * At the point where the event is dispatched the changes have already been applied, meaning
- * the mapping stored in the event can be queried for its post-change state
+ * <p>At the point where the event is dispatched the changes have already been applied, meaning
+ * the mapping stored in the event can be queried for its post-change state</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.MappingEvent
+ * @eventType org.swiftsuspenders.MappingEvent.POST_MAPPING_CHANGE
*/
[Event(name='postMappingChange', type='org.swiftsuspenders.MappingEvent')]
/**
* This event is dispatched each time an injector mapping is removed, right after
* the mapping is deleted from the configuration.
*
- * At the point where the event is dispatched the changes have already been applied, meaning
- * the mapping is lost to the injector and can't be queried anymore
+ * <p>At the point where the event is dispatched the changes have already been applied, meaning
+ * the mapping is lost to the injector and can't be queried anymore.</p>
*
- * This event is only dispatched when there are one or more relevant listeners
- * attached to the dispatching injector.
+ * <p>This event is only dispatched when there are one or more relevant listeners attached to
+ * the dispatching injector.</p>
*
- * @eventType org.swiftsuspenders.MappingEvent
+ * @eventType org.swiftsuspenders.MappingEvent.POST_MAPPING_REMOVE
*/
[Event(name='postMappingRemove', type='org.swiftsuspenders.MappingEvent')]
-
+ /**
+ * The <code>Injector</code> manages the mappings and acts as the central hub from which all
+ * injections are started.
+ */
public class Injector extends EventDispatcher
{
//---------------------- Private / Protected Properties ----------------------//
@@ -164,12 +167,42 @@ package org.swiftsuspenders
_applicationDomain = ApplicationDomain.currentDomain;
}
+ /**
+ * Maps a request description, consisting of the <code>type</code> and, optionally, the
+ * <code>name</code>.
+ *
+ * <p>The returned mapping is created if it didn't exist yet or simply returned otherwise.</p>
+ *
+ * <p>Named mappings should be used as sparingly as possible as they increase the likelyhood
+ * of typing errors to cause hard to debug errors at runtime.</p>
+ *
+ * @param type The <code>class</code> describing the mapping
+ * @param name The name, as a case-sensitive string, to further describe the mapping
+ *
+ * @return The <code>InjectionMapping</code> for the given request description
+ *
+ * @see #unmap()
+ * @see InjectionMapping
+ */
public function map(type : Class, name : String = '') : InjectionMapping
{
const mappingId : String = getQualifiedClassName(type) + '|' + name;
return _mappings[mappingId] || createMapping(type, name, mappingId);
}
+ /**
+ * Removes the mapping described by the given <code>type</code> and <code>name</code>.
+ *
+ * @param type The <code>class</code> describing the mapping
+ * @param name The name, as a case-sensitive string, to further describe the mapping
+ *
+ * @throws org.swiftsuspenders.InjectorError Descriptions that are not mapped can't be unmapped
+ * @throws org.swiftsuspenders.InjectorError Sealed mappings have to be unsealed before unmapping them
+ *
+ * @see #map()
+ * @see InjectionMapping
+ * @see InjectionMapping#unseal()
+ */
public function unmap(type : Class, name : String = '') : void
{
const mappingId : String = getQualifiedClassName(type) + '|' + name;
@@ -194,6 +227,7 @@ package org.swiftsuspenders
* by using a mapping of its own or by querying one of its ancestor injectors.
*
* @param type The dependency under query
+ *
* @return <code>true</code> if the dependency can be satisfied, <code>false</code> if not
*/
public function satisfies(type : Class, name : String = '') : Boolean
@@ -203,12 +237,13 @@ package org.swiftsuspenders
/**
* Indicates whether the injector can directly supply a response for the specified
- * dependency
+ * dependency.
*
- * In contrast to <code>satisfies</code>, <code>satisfiesDirectly</code> only informs
- * about mappings on this injector itself, without querying its ancestor injectors.
+ * <p>In contrast to <code>#satisfies()</code>, <code>satisfiesDirectly</code> only informs
+ * about mappings on this injector itself, without querying its ancestor injectors.</p>
*
* @param type The dependency under query
+ *
* @return <code>true</code> if the dependency can be satisfied, <code>false</code> if not
*/
public function satisfiesDirectly(type : Class, name : String = '') : Boolean
@@ -219,15 +254,17 @@ package org.swiftsuspenders
/**
* Returns the mapping for the specified dependency class
*
- * Note that getMapping will only return mappings in exactly this injector, not ones
+ * <p>Note that getMapping will only return mappings in exactly this injector, not ones
* mapped in an ancestor injector. To get mappings from ancestor injectors, query them
* using <code>parentInjector</code>.
* This restriction is in place to prevent accidential changing of mappings in ancestor
- * injectors where only the child's response is meant to be altered.
+ * injectors where only the child's response is meant to be altered.</p>
*
* @param type The dependency to return the mapping for
+ *
* @return The mapping for the specified dependency class
- * @throws InjectorError when no mapping was found for the specified dependency
+ *
+ * @throws InjectorError When no mapping was found for the specified dependency
*/
public function getMapping(type : Class, name : String = '') : InjectionMapping
{
@@ -241,6 +278,15 @@ package org.swiftsuspenders
return mapping;
}
+ /**
+ * Inspects the given object and injects into all injection points configured for its class.
+ *
+ * @param target The instance to inject into
+ *
+ * @throws org.swiftsuspenders.InjectorError The <code>Injector</code> must have mappings for all injection points
+ *
+ * @see #map()
+ */
public function injectInto(target : Object) : void
{
const type : Class = getConstructor(target);
@@ -249,6 +295,17 @@ package org.swiftsuspenders
applyInjectionPoints(target, type, ctorInjectionPoint.next);
}
+ /**
+ * Instantiates the class identified by the given <code>type</code> and <code>name</code>.
+ *
+ * <p>If no <code>InjectionMapping</code> is found for the given <code>type</code> and no
+ * <code>name</code> is given, the class is simply instantiated and then injected into.</p>
+ *
+ * @param type The <code>class</code> describing the mapping
+ * @param name The name, as a case-sensitive string, to further describe the mapping
+ *
+ * @return The created instance
+ */
public function getInstance(type : Class, name : String = '') : *
{
const mappingId : String = getQualifiedClassName(type) + '|' + name;
@@ -264,19 +321,44 @@ package org.swiftsuspenders
}
return instantiateUnmapped(type, type);
}
-
+
+ /**
+ * Creates a new <code>Injector</code> and sets itself as that new <code>Injector</code>'s
+ * <code>parentInjector</code>.
+ *
+ * @param applicationDomain The optional domain to use in the new Injector.
+ * If not given, the creating injector's domain is set on the new Injector as well.
+ * @return The newly created <code>Injector</code> instance
+ *
+ * @see #parentInjector
+ */
public function createChildInjector(applicationDomain : ApplicationDomain = null) : Injector
{
var injector : Injector = new Injector();
- injector.applicationDomain = applicationDomain;
+ injector.applicationDomain = applicationDomain || this.applicationDomain;
injector.parentInjector = this;
return injector;
}
+ /**
+ * Sets the <code>Injector</code> to ask in case the current <code>Injector</code> doesn't
+ * have a mapping for a dependency.
+ *
+ * <p>Parent Injectors can be nested in arbitrary depths with very little overhead,
+ * enabling very modular setups for the managed object graphs.</p>
+ *
+ * @param parentInjector The <code>Injector</code> to use for dependencies the current
+ * <code>Injector</code> can't supply
+ */
public function set parentInjector(parentInjector : Injector) : void
{
_parentInjector = parentInjector;
}
+
+ /**
+ * Returns the <code>Injector</code> used for dependencies the current
+ * <code>Injector</code> can't supply
+ */
public function get parentInjector() : Injector
{
return _parentInjector;
View
3 src/org/swiftsuspenders/MappingEvent.as
@@ -20,9 +20,6 @@ package org.swiftsuspenders
/**
* @eventType postMappingChange
*/
- /**
- * @eventType postMappingChange
- */
public static const POST_MAPPING_CHANGE : String = 'postMappingChange';
/**
* @eventType postMappingRemove

0 comments on commit 21051a0

Please sign in to comment.
Something went wrong with that request. Please try again.