Docs update

lib/Minify.php

@@ -3,7 +3,7 @@
 /**
  * Minify - Combines, minifies, and caches JavaScript and CSS files on demand.
  *
- * See http://code.google.com/p/minify/ for usage instructions.
+ * See README for usage instructions (for now).
  *
  * This library was inspired by jscsscomp by Maxim Martynyuk <flashkot@mail.ru>
  * and by the article "Supercharged JavaScript" by Patrick Hunlock
@@ -59,6 +59,8 @@ class Minify {
      * 
      * @param array $spec options for the controller's constructor
      * 
+     * @param array $options options passed on to Minify
+     *
      * @return mixed a Minify controller object
      */
     public static function serve($type, $spec = array(), $options = array()) {
@@ -191,7 +193,9 @@ class Minify {
             ,'encodeLevel' => 9
             ,'perType' => array() // per-type minifier options
             ,'contentTypeCharset' => null // leave out of Content-Type header
-            ,'cacheUntil' => null
+            
+            // @todo: rename option "setExpires" ?
+            ,'cacheUntil' => null // send Expires header
         ), $given);
         $defaultMinifiers = array(
             'text/css' => array('Minify_CSS', 'minify')

lib/Minify/Controller/Base.php

@@ -24,7 +24,12 @@ class Minify_Controller_Base {
      * 
      * 'minifiers': this is an array with content-types as keys and callbacks as
      * values. Specify a custom minifier by setting this option. E.g.:
-     * $this->options['minifiers']['application/x-javascript'] = 'myJsPacker';
+     * 
+     * <code>
+     * $this->options['minifiers']['application/x-javascript'] = 
+     *     array('Minify_Packer', 'minify'); // callback
+     * </code>
+     * 
      * Note that, when providing your own minifier, the controller must be able
      * to load its code on demand. @see loadMinifier()
      * 
@@ -68,19 +73,22 @@ class Minify_Controller_Base {
     /**
      * Parent constructor for a controller class
      * 
-     * Generally you'll call this at the end of your child class constructor:
+     * If your subclass controller is not happy with the request, it can simply return
+     * without setting $this->requestIsValid. Minify will not check any other member.
+     * 
+     * If the request is valid, you must set $this->requestIsValid = true and also call
+     * the parent constructor, passing along an array of source objects and any Minify 
+     * options:
      * <code>
      * parent::__construct($sources, $options);
      * </code>
      * 
-     * This function sets the sources and determines the 'contentType' and 
-     * 'lastModifiedTime', if not given.
+     * This function sets $this->sources and determines $this->options 'contentType' and 
+     * 'lastModifiedTime'.
      * 
-     * If no sources are provided, $this->requestIsValid will be set to false.
+     * @param array $sources array of Minify_Source instances
      * 
-     * @param array $sources array of instances of Minify_Source
-     * 
-     * @param array $options
+     * @param array $options options for Minify
      * 
      * @return null
      */

lib/Minify/Controller/Files.php

@@ -5,10 +5,10 @@ require_once 'Minify/Controller/Base.php';
 /**
  * Controller class for minifying a set of files
  * 
- * E.g. the following would serve minified Javascript for a site
+ * E.g. the following would serve the minified Javascript for a site
  * <code>
  * $dr = $_SERVER['DOCUMENT_ROOT'];
- * Minify::minify('Files', array(
+ * Minify::serve('Files', array(
  *    $dr . '/js/jquery.js'
  *     ,$dr . '/js/plugins.js'
  *     ,$dr . '/js/site.js'
@@ -19,9 +19,9 @@ require_once 'Minify/Controller/Base.php';
 class Minify_Controller_Files extends Minify_Controller_Base {
     
     /**
-     * @param array $spec array or full paths of files to be minified
+     * @param array $spec array of full paths of files to be minified
      * 
-     * @param array $options optional options to pass to Minify
+     * @param array $options options to pass to Minify
      * 
      * @return null 
      */

lib/Minify/Controller/Groups.php

@@ -8,7 +8,7 @@ require_once 'Minify/Controller/Base.php';
  * 
  * <code>
  * $dr = $_SERVER['DOCUMENT_ROOT'];
- * Minify::minify('Groups', array(
+ * Minify::serve('Groups', array(
  *   'css' => array(
  *     $dr . '/css/type.css'
  *     ,$dr . '/css/layout.css'
@@ -47,6 +47,7 @@ class Minify_Controller_Groups extends Minify_Controller_Base {
                     'filepath' => $file
                 ));    
             } else {
+                // file doesn't exist
                 return;
             }
         }

lib/Minify/Controller/Page.php

@@ -3,23 +3,20 @@
 require_once 'Minify/Controller/Base.php';
 
 /**
- * Controller class for minifying a set of files
+ * Controller class for serving a single HTML page
  * 
- * E.g. the following would serve minified Javascript for a site
- * <code>
- * $dr = $_SERVER['DOCUMENT_ROOT'];
- * Minify::minify('Files', array(
- *    $dr . '/js/jquery.js'
- *     ,$dr . '/js/plugins.js'
- *     ,$dr . '/js/site.js'
- * ));
- * </code>
+ * @link http://code.google.com/p/minify/source/browse/trunk/web/examples/1/index.php#59
  * 
  */
 class Minify_Controller_Page extends Minify_Controller_Base {
     
     /**
+     * @param array $spec array of options. You *must* set 'content' and 'id',
+     * but setting 'lastModifiedTime' is recommeded in order to allow server
+     * and client-side caching.
      * 
+     * If you set <code>'minifyAll' => 1</code>, all CSS and Javascript blocks
+     * will be individually minified. 
      * 
      * @param array $options optional options to pass to Minify
      * 
@@ -49,13 +46,18 @@ class Minify_Controller_Page extends Minify_Controller_Base {
     
     private $_loadCssJsMinifiers = false;
     
+    /**
+     * @see Minify_Controller_Base::loadMinifier()
+     */
     public function loadMinifier($minifierCallback)
     {
         if ($this->_loadCssJsMinifiers) {
+            // Minify will not call for these so we must manually load
+            // them when Minify/HTML.php is called for.
             require 'Minify/CSS.php';
             require 'Minify/Javascript.php';
         }
-        parent::loadMinifier($minifierCallback);
+        parent::loadMinifier($minifierCallback); // load Minify/HTML.php
     }
 }