Merge pull request #111 from nubs/attributes

Update documentation of attributes

Author: clue

lib/Fhaculty/Graph/Attribute/AttributeBag.php

@@ -7,7 +7,7 @@
  */
 interface AttributeBag extends AttributeAware
 {
-    // public function getAttribute($name);
+    // public function getAttribute($name, $default);
     // public function setAttribute($name, $value);
     // public function getAttributeBag();
 

lib/Fhaculty/Graph/Attribute/AttributeBagContainer.php

@@ -2,34 +2,73 @@
 
 namespace Fhaculty\Graph\Attribute;
 
+/**
+ * A fairly standard AttributeBag container.
+ *
+ * This container passes and returns attributes by value.  It is mutable,
+ * however, so multiple references to the container will update in kind.
+ */
 class AttributeBagContainer implements AttributeBag
 {
+    /**
+     * @var array
+     */
     private $attributes = array();
 
+    /**
+     * get a single attribute with the given $name (or return $default if attribute was not found)
+     *
+     * @param  string $name
+     * @param  mixed  $default to return if attribute was not found
+     * @return mixed
+     */
     public function getAttribute($name, $default = null)
     {
         return isset($this->attributes[$name]) ? $this->attributes[$name] : $default;
     }
 
+    /**
+     * set a single attribute with the given $name to given $value
+     *
+     * @param  string $name
+     * @param  mixed  $value
+     * @return self   For a fluid interface.
+     */
     public function setAttribute($name, $value)
     {
         $this->attributes[$name] = $value;
 
         return $this;
     }
 
+    /**
+     * get an array of all attributes
+     *
+     * @return array
+     */
     public function getAttributes()
     {
         return $this->attributes;
     }
 
+    /**
+     * set an array of additional attributes
+     *
+     * @param  array $attributes
+     * @return self  For a fluid interface.
+     */
     public function setAttributes(array $attributes)
     {
         $this->attributes = $attributes + $this->attributes;
 
         return $this;
     }
 
+    /**
+     * get a container for all attributes
+     *
+     * @return AttributeBag
+     */
     public function getAttributeBag()
     {
         return $this;

lib/Fhaculty/Graph/Attribute/AttributeBagNamespaced.php

@@ -3,13 +3,34 @@
 namespace Fhaculty\Graph\Attribute;
 
 /**
- * An attribute bag that automatically prefixes a given namespace
+ * An attribute bag that automatically prefixes a given namespace.
+ *
+ * For example, you can use this class to prefix the attributes using a vendor
+ * name, like "myvendor.item.".  If another vendor shares the base attribute
+ * bag, it can use a different prefix, like "otherProduct.item.".  This allows
+ * both libraries to have attributes with the same name without having them
+ * conflict.  For example, the attribute "id" would be stored separately as
+ * "myvendor.item.id" and "otherProduct.item.id".
  */
 class AttributeBagNamespaced implements AttributeBag
 {
+    /**
+     * @var AttributeBag
+     */
     private $bag;
+
+    /**
+     * @var string
+     */
     private $prefix;
 
+    /**
+     * Initialize the attribute bag with a prefix to use as a namespace for the attributes.
+     *
+     * @param AttributeAware $bag    The bag to store the prefixed attributes in.
+     * @param string         $prefix The prefix to prepend to all attributes before
+     *                               storage.  This prefix acts as a namespace to separate attributes.
+     */
     public function __construct(AttributeAware $bag, $prefix)
     {
         if (!($bag instanceof AttributeBag)) {
@@ -19,16 +40,41 @@ public function __construct(AttributeAware $bag, $prefix)
         $this->prefix = $prefix;
     }
 
+    /**
+     * get a single attribute with the given $name (or return $default if attribute was not found)
+     *
+     * This prefixes the attribute name before requesting from the base bag.
+     *
+     * @param string $name
+     * @param mixed  $default to return if attribute was not found
+     * @return mixed
+     */
     public function getAttribute($name, $default = null)
     {
         return $this->bag->getAttribute($this->prefix . $name, $default);
     }
 
+    /**
+     * set a single attribute with the given $name to given $value
+     *
+     * This prefixes the attribute name before setting in the base bag.
+     *
+     * @param  string $name
+     * @param  mixed  $value
+     * @return void
+     */
     public function setAttribute($name, $value)
     {
         $this->bag->setAttribute($this->prefix . $name, $value);
     }
 
+    /**
+     * get an array of all attributes
+     *
+     * The prefix will not be included in the returned attribute keys.
+     *
+     * @return array
+     */
     public function getAttributes()
     {
         $attributes = array();
@@ -43,13 +89,26 @@ public function getAttributes()
         return $attributes;
     }
 
+    /**
+     * set an array of additional attributes
+     *
+     * Each attribute is prefixed before setting in the base bag.
+     *
+     * @param  array $attributes
+     * @return void
+     */
     public function setAttributes(array $attributes)
     {
         foreach ($attributes as $name => $value) {
             $this->bag->setAttribute($this->prefix . $name, $value);
         }
     }
 
+    /**
+     * get a container for all attributes
+     *
+     * @return AttributeBag
+     */
     public function getAttributeBag()
     {
         return $this;

lib/Fhaculty/Graph/Attribute/AttributeBagReference.php

@@ -2,39 +2,87 @@
 
 namespace Fhaculty\Graph\Attribute;
 
+/**
+ * The basic attribute bag, but using a reference to the base attribute array.
+ *
+ * This container passes and returns attributes by value, but stores them in a
+ * pass-by-reference array.  It is mutable, however, so multiple references to
+ * the container will update in kind.
+ */
 class AttributeBagReference implements AttributeBag
 {
+    /**
+     * @var array
+     */
     private $attributes;
 
+    /**
+     * Initialize the attribute bag with the base attribute array.
+     *
+     * The given array is pass-by-reference, so updates to the array here or in
+     * calling code will be reflected everywhere.
+     *
+     * @param array $attributes The pass-by-reference attributes.
+     */
     public function __construct(array &$attributes)
     {
         $this->attributes =& $attributes;
     }
 
+    /**
+     * get a single attribute with the given $name (or return $default if attribute was not found)
+     *
+     * @param  string $name
+     * @param  mixed  $default to return if attribute was not found
+     * @return mixed
+     */
     public function getAttribute($name, $default = null)
     {
         return isset($this->attributes[$name]) ? $this->attributes[$name] : $default;
     }
 
+    /**
+     * set a single attribute with the given $name to given $value
+     *
+     * @param  string $name
+     * @param  mixed  $value
+     * @return self   For a fluid interface.
+     */
     public function setAttribute($name, $value)
     {
         $this->attributes[$name] = $value;
 
         return $this;
     }
 
+    /**
+     * get an array of all attributes
+     *
+     * @return array
+     */
     public function getAttributes()
     {
         return $this->attributes;
     }
 
+    /**
+     * set an array of additional attributes
+     *
+     * @param  array $attributes
+     * @return self  For a fluid interface.
+     */
     public function setAttributes(array $attributes)
     {
         $this->attributes = $attributes + $this->attributes;
 
         return $this;
     }
 
+    /**
+     * get a container for all attributes
+     *
+     * @return AttributeBag
+     */
     public function getAttributeBag()
     {
         return $this;