From 046ad2b96846c9be370125719ff78fb02531597f Mon Sep 17 00:00:00 2001
From: Amit Snyderman <amit@amitsnyderman.com>
Date: Mon, 16 Sep 2013 20:50:47 -0400
Subject: [PATCH] Docs

---
 src/Mustache/Cache.php                 | 20 ++++++++++
 src/Mustache/Cache/AbstractCache.php   |  7 ++++
 src/Mustache/Cache/FilesystemCache.php | 53 ++++++++++++++++++++++++++
 src/Mustache/Cache/NoopCache.php       | 19 +++++++++
 4 files changed, 99 insertions(+)

diff --git a/src/Mustache/Cache.php b/src/Mustache/Cache.php
index 1561efc..1ca7438 100644
--- a/src/Mustache/Cache.php
+++ b/src/Mustache/Cache.php
@@ -9,8 +9,28 @@
  * file that was distributed with this source code.
  */
 
+/**
+ * Mustache Cache interface.
+ *
+ * Interface for caching and loading Mustache_Template classes
+ * generated by the Mustache_Compiler.
+ */
 interface Mustache_Cache
 {
+    /**
+     * Load a compiled Mustache_Template class from cache.
+     *
+     * @param  string $key
+     * @return boolean indicates successfully class load
+     */
     public function load($key);
+
+    /**
+     * Cache and load a compiled Mustache_Template class.
+     *
+     * @param  string $key
+     * @param  string $value
+     * @return void
+     */
     public function cache($key, $value);
 }
diff --git a/src/Mustache/Cache/AbstractCache.php b/src/Mustache/Cache/AbstractCache.php
index dc67387..4a5ab90 100644
--- a/src/Mustache/Cache/AbstractCache.php
+++ b/src/Mustache/Cache/AbstractCache.php
@@ -9,6 +9,13 @@
  * file that was distributed with this source code.
  */
 
+/**
+ * Abstract Mustache Cache class.
+ *
+ * Provides logging support to child implementations.
+ *
+ * @abstract
+ */
 abstract class Mustache_Cache_AbstractCache implements Mustache_Cache
 {
     private $logger = null;
diff --git a/src/Mustache/Cache/FilesystemCache.php b/src/Mustache/Cache/FilesystemCache.php
index 8b100ef..ade547d 100644
--- a/src/Mustache/Cache/FilesystemCache.php
+++ b/src/Mustache/Cache/FilesystemCache.php
@@ -9,17 +9,39 @@
  * file that was distributed with this source code.
  */
 
+/**
+ * Mustache Cache filesystem implementation.
+ *
+ * A FilesystemCache instance caches Mustache Template classes from the filesystem by name:
+ *
+ *     $cache = new Mustache_Cache_FilesystemCache(dirname(__FILE__).'/cache');
+ *     $cache->cache($className, $compiledSource);
+ *
+ * Benefits from any opcode caching that may be setup in your environment.
+ */
 class Mustache_Cache_FilesystemCache extends Mustache_Cache_AbstractCache
 {
     private $baseDir;
     private $fileMode;
 
+    /**
+     * Filesystem cache constructor.
+     *
+     * @param string $baseDir Directory for compiled templates.
+     * @param int $fileMode Override default permissions for cache files. Defaults to using the system-defined umask.
+     */
     public function __construct($baseDir, $fileMode = null)
     {
         $this->baseDir = $baseDir;
         $this->fileMode = $fileMode;
     }
 
+    /**
+     * Load the class from cache using `require_once`.
+     *
+     * @param  string $key
+     * @return boolean
+     */
     public function load($key)
     {
         $fileName = $this->getCacheFilename($key);
@@ -32,6 +54,13 @@ class Mustache_Cache_FilesystemCache extends Mustache_Cache_AbstractCache
         return true;
     }
 
+    /**
+     * Cache and load the compiled class
+     *
+     * @param  string $key
+     * @param  string $value
+     * @return void
+     */
     public function cache($key, $value)
     {
         $fileName = $this->getCacheFilename($key);
@@ -46,11 +75,26 @@ class Mustache_Cache_FilesystemCache extends Mustache_Cache_AbstractCache
         $this->load($key);
     }
 
+    /**
+     * Build the cache filename.
+     * Subclasses should override for custom cache directory structures.
+     *
+     * @param  string $name
+     * @return string
+     */
     protected function getCacheFilename($name)
     {
         return sprintf('%s/%s.php', $this->baseDir, $name);
     }
 
+    /**
+     * Create cache directory
+     *
+     * @param  string $fileName
+     * @return string
+     *
+     * @throws Mustache_Exception_RuntimeException If unable to create directory
+     */
     private function buildDirectoryForFilename($fileName)
     {
         $dirName = dirname($fileName);
@@ -69,6 +113,15 @@ class Mustache_Cache_FilesystemCache extends Mustache_Cache_AbstractCache
         return $dirName;
     }
 
+    /**
+     * Write cache file
+     *
+     * @param  string $fileName
+     * @param  string $value
+     * @return void
+     *
+     * @throws Mustache_Exception_RuntimeException If unable to write file
+     */
     private function writeFile($fileName, $value)
     {
         $dirName = $this->buildDirectoryForFilename($fileName);
diff --git a/src/Mustache/Cache/NoopCache.php b/src/Mustache/Cache/NoopCache.php
index df3fbf0..bd54362 100644
--- a/src/Mustache/Cache/NoopCache.php
+++ b/src/Mustache/Cache/NoopCache.php
@@ -9,13 +9,32 @@
  * file that was distributed with this source code.
  */
 
+/**
+ * Mustache Cache in-memory implementation.
+ *
+ * In-memory implementation useful during development.
+ * Not recommended for production use.
+ */
 class Mustache_Cache_NoopCache extends Mustache_Cache_AbstractCache
 {
+    /**
+     * Loads nothing. Move along.
+     *
+     * @param  string $key
+     * @return boolean
+     */
     public function load($key)
     {
         return false;
     }
 
+    /**
+     * Loads the compiled Mustache Template class without caching.
+     *
+     * @param  string $key
+     * @param  string $compiled
+     * @return void
+     */
     public function cache($key, $compiled)
     {
         $this->log(