Document MergeReplaceKey/MergeRemoveKey features

Documents how the MergeReplaceKey and MergeRemoveKey features work, and
that they require the developer to install zend-stdlib if they wish to
use them.

Author: weierophinney

composer.json

@@ -24,7 +24,8 @@
         "athletic/athletic": "dev-master"
     },
     "suggest": {
-        "ocramius/proxy-manager": "ProxyManager 1.* to handle lazy initialization of services"
+        "ocramius/proxy-manager": "ProxyManager 1.* to handle lazy initialization of services",
+        "zendframework/zend-stdlib": "zend-stdlib ^2.5 if you wish to use the MergeReplaceKey or MergeRemoveKey features in Config instances"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,

src/Config.php

@@ -12,6 +12,21 @@
 use Zend\Stdlib\ArrayUtils\MergeRemoveKey;
 use Zend\Stdlib\ArrayUtils\MergeReplaceKeyInterface;
 
+/**
+ * Object for defining configuration and configuring an existing service manager instance.
+ *
+ * In order to provide configuration merging capabilities, this class implements
+ * the same functionality as `Zend\Stdlib\ArrayUtils::merge()`. That routine
+ * allows developers to specifically shape how values are merged:
+ *
+ * - A value which is an instance of `MergeRemoveKey` indicates the value should
+ *   be removed during merge.
+ * - A value that is an instance of `MergeReplaceKeyInterface` indicates that the
+ *   value it contains should be used to replace any previous versions.
+ *
+ * These features are advanced, and not typically used. If you wish to use them,
+ * you will need to require the zend-stdlib package in your application.
+ */
 class Config implements ConfigInterface
 {
     /**