Reformat comments

lib/Broker.php

@@ -3,14 +3,16 @@
 namespace Byron;
 
 /**
- * The Broker system is merely a more structured way of creating a no-argument function
- * for each service that returns an object appropriately configured (with correct hostnames,
- * usernames, passwords, etc.) for interacting with that service.
+ * The Broker system is merely a more structured way of creating a no-argument
+ * function for each service that returns an object appropriately configured
+ * (with correct hostnames, usernames, passwords, etc.) for interacting with
+ * that service.
  *
- * That is, the constructor for a low-level library function will probably have arguments
- * like hostname, username, password, etc.  It's incovenient and annoying to have to
- * figure out how and where these details should come from every time you want to use
- * the service.  You could create a big PHP file with a function for each service:
+ * That is, the constructor for a low-level library function will probably have
+ * arguments like hostname, username, password, etc.  It's incovenient and
+ * annoying to have to figure out how and where these details should come from
+ * every time you want to use the service.  You could create a big PHP file with
+ * a function for each service:
  *
  *     function getMySQLService() {
  *         // extract connection details from a (global?) variable
@@ -19,12 +21,12 @@
  *     }
  *
  * But this is a bit messy and unclean.  The alternative is to create a "Broker"
- * object, giving it a mechanism to create an appropriate class names for a service,
- * when that service is requested.  Then the broker can instantiate that class, passing
- * it any information it might need, like an object storing configuration details.
- * Then, the broker could call a "getService()" method on the newly-instantiated object,
- * returning the return value of "getService()" to the caller.  This is the mechanism
- * implemented by this class.
+ * object, giving it a mechanism to create an appropriate class names for a
+ * service, when that service is requested.  Then the broker can instantiate
+ * that class, passing it any information it might need, like an object storing
+ * configuration details. Then, the broker could call a "getService()" method on
+ * the newly-instantiated object, returning the return value of "getService()"
+ * to the caller.  This is the mechanism implemented by this class.
  *
  * See http://martinfowler.com/articles/injection.html#UsingAServiceLocator
  */
@@ -104,4 +106,3 @@ public function __call($name, $args) {
     }
 
 }
-

lib/Cache.php

@@ -6,9 +6,9 @@ interface Cache {
 
     /**
      * Retrieves value associated with $key from the cache backend.  Because
-     * backends indicate "not found" in different ways, consumers must
-     * assume that any return value that satisfies empty() is a cache miss,
-     * and act accordingly.
+     * backends indicate "not found" in different ways, consumers must assume
+     * that any return value that satisfies empty() is a cache miss, and act
+     * accordingly.
      * 
      * @param $key
      * @return mixed
@@ -29,8 +29,8 @@ public function add($key, $value, $expires = null);
 
     /**
      * Saves the $key/$value pair to the cache backend.  Saving anything for
-     * that is empty() is not supported--even if this value makes it through
-     * to the backend, other clients will assume any such value returned is
+     * that is empty() is not supported--even if this value makes it through to
+     * the backend, other clients will assume any such value returned is
      * equivalent to a cache miss.  (Classes extending this class should check
      * to see if empty($value) is true, and throw an error if so.)
      * 

lib/Client.php

@@ -3,13 +3,14 @@
 namespace Byron;
 
 /**
- * \Byron\Client extends \Zend_Http_Client, and behaves like it in most respects.
- * However, there are two crucial differences: (1) the constructor takes a "key", which
- * will generally be an API key, or a datastructure representing an API key; and (2)
- * the return value of an actual request can be configured to be just the body of the 
- * response, and not the response object itself.  (This is useful if the service
- * you're talking to isn't very RESTful, and pretty much always returns a 200, embedding
- * the real status in the body of the response.)
+ * \Byron\Client extends \Zend_Http_Client, and behaves like it in most
+ * respects. However, there are two crucial differences: (1) the constructor
+ * takes a "key", which will generally be an API key, or a datastructure
+ * representing an API key; and (2) the return value of an actual request can be
+ * configured to be just the body of the response, and not the response object
+ * itself.  (This is useful if the service you're talking to isn't very RESTful,
+ * and pretty much always returns a 200, embedding the real status in the body
+ * of the response.)
  */
 
 class Client extends \Zend_Http_Client
@@ -23,12 +24,13 @@ class Client extends \Zend_Http_Client
     protected $key = null;
 
     /**
-     * Whether to return a response object, or the raw response body.  The value you
-     * want more or less depends on how RESTful the service you're talking to is.  If
-     * it's very RESTful (e.g. 404 indicates something is missing, rather than an
-     * error), then you probably want the response object.  On the other hand, if the
-     * server pretty much always returns a 200 response, and embeds error messages
-     * in the content itself, then you probably want the raw response body.
+     * Whether to return a response object, or the raw response body.  The value
+     * you want more or less depends on how RESTful the service you're talking
+     * to is.  If it's very RESTful (e.g. 404 indicates something is missing,
+     * rather than an error), then you probably want the response object.  On
+     * the other hand, if the server pretty much always returns a 200 response,
+     * and embeds error messages in the content itself, then you probably want
+     * the raw response body.
      *
      * @var boolean
      */
@@ -111,10 +113,11 @@ public function POST($url, $args = array())
     }
 
     /**
-     * Perform the actual request using the client instance.  If the instance variable
-     * $returnResponseObject is true a Zend_Http_Response is returned, otherwise the
-     * response body only is returned.  (In this case some basic error checking
-     * is performed--an exception is thrown if the server returned a 404, for example.)
+     * Perform the actual request using the client instance.  If the instance
+     * variable $returnResponseObject is true a Zend_Http_Response is returned,
+     * otherwise the response body only is returned.  (In this case some basic
+     * error checking is performed--an exception is thrown if the server
+     * returned a 404, for example.)
      *
      * @return Zend_Http_Response|string
      * @throws Service_Exception

lib/Config.php

@@ -1,13 +1,12 @@
 <?php
 
 /**
- * Simple routines for restoring and retrieving configuration 
- * information based around the PHP function parse_ini_file().
+ * Simple routines for restoring and retrieving configuration information based
+ * around the PHP function parse_ini_file().
  *
- * getMandatory() and getOptional() are used in preference
- * to get() with some arguments because I kept forgetting
- * what the arguments meant, and their order.  It's better
- * this way, trust me!
+ * getMandatory() and getOptional() are used in preference to get() with some
+ * arguments because I kept forgetting what the arguments meant, and their
+ * order.  It's better this way, trust me!
  * 
  * @license MIT
  * @author Michael Stillwell <mjs@beebo.org>
@@ -43,12 +42,12 @@ public static function getInstance() {
     }
 
     /**
-     * Loads the configuration information given in file $filename into
-     * the configuration object.  This uses the function parse_ini_file()
+     * Loads the configuration information given in file $filename into the
+     * configuration object.  This uses the function parse_ini_file()
      * internally, so the passed file should be compatible with it.
      *
-     * If load is called multiple times, the configuration settings are 
-     * merged; in the case of a conflict, last file wins.
+     * If load is called multiple times, the configuration settings are merged;
+     * in the case of a conflict, last file wins.
      *
      * @param string $filename
      */
@@ -87,8 +86,8 @@ public function exists($k) {
     }
 
     /**
-     * Returns the configuration value associated with key $k, dying if
-     * it does not exist.
+     * Returns the configuration value associated with key $k, dying if it does
+     * not exist.
      *
      * @param string $k
      * @return mixed

lib/DOM.php

@@ -5,8 +5,9 @@
 class DOM {
 
     /**
-     * Takes the filename of a HTML file, returns a proxied DOMDocument object that
-     * does everything a DOMDocument does, but with some extra convenience functions.
+     * Takes the filename of a HTML file, returns a proxied DOMDocument object
+     * that does everything a DOMDocument does, but with some extra convenience
+     * functions.
      *
      * @param string $filename
      * @return \Byron\DOM\DOMDocument Does everything a DOMDocument does, but has additional helper functions
@@ -19,8 +20,8 @@ static function loadHtmlFile($filename) {
     }
 
     /**
-     * Takes an HTML string, returns a proxied DOMDocument object that
-     * does everything a DOMDocument does, but with some extra convenience functions.
+     * Takes an HTML string, returns a proxied DOMDocument object that does
+     * everything a DOMDocument does, but with some extra convenience functions.
      *
      * @param string $s XML string
      * @return \Byron\DOM\DOMDocument Does everything a DOMDocument does, but has additional helper functions
@@ -33,11 +34,12 @@ static function loadHtml($s) {
     }
 
     /**
-     * Takes the filename of an XML file, returns a proxied DOMDocument object that
-     * does everything a DOMDocument does, but with some extra convenience functions.
+     * Takes the filename of an XML file, returns a proxied DOMDocument object
+     * that does everything a DOMDocument does, but with some extra convenience
+     * functions.
      *
-     * (This is equivalent to load() in the DOMDocument API, but is renamed here for
-     * consistency.)
+     * (This is equivalent to load() in the DOMDocument API, but is renamed here
+     * for consistency.)
      *
      * @param string $filename
      * @return \Byron\DOM\DOMDocument Does everything a DOMDocument does, but has additional helper functions
@@ -63,8 +65,8 @@ static function loadXmlFile($filename, $transform = false)
     }
 
     /**
-     * Takes an XML string, returns a proxied DOMDocument object that
-     * does everything a DOMDocument does, but with some extra convenience functions.
+     * Takes an XML string, returns a proxied DOMDocument object that does
+     * everything a DOMDocument does, but with some extra convenience functions.
      *
      * @param string $s XML string
      * @return \Byron\DOM\DOMDocument Does everything a DOMDocument does, but has additional helper functions

lib/Geo.php

@@ -11,10 +11,10 @@
 class Geo {
 
     /**
-     * Returns a list consisting of the number of meters per angle of 
-     * latitude and longitude (measured in degrees) at the specified latitude. 
-     * These values may be used for fast approximations of distance
-     * calculations in the vicinity of some location.
+     * Returns a list consisting of the number of meters per angle of latitude
+     * and longitude (measured in degrees) at the specified latitude. These
+     * values may be used for fast approximations of distance calculations in
+     * the vicinity of some location.
      *
      *   list( $lat_scale, $lon_scale ) = $geo->scales($lat0);
      *   $x = $lon_scale * ($lon - $lon0); 
@@ -58,8 +58,8 @@ public static function scales($lat) {
     }
 
     /**
-     * Returns a bounding box centered on a point given by ($lat, $lon), with a boundary of
-     * $meters to the north, south, east and west.
+     * Returns a bounding box centered on a point given by ($lat, $lon), with a
+     * boundary of $meters to the north, south, east and west.
      *
      * @param float $lat the latitude around which the bounding box will be centered
      * @param float $lon the longitude around which the bounding box will be centered

lib/PDO.php

@@ -7,29 +7,27 @@
  *    so that database connections are re-used.
  *  * A few convenience SQL-generation methods are added.
  * 
- * The general philosphy with this is: don't worry about writing some
- * code to generate the SQL for you: bust out raw SQL early and
- * often.
+ * The general philosphy with this is: don't worry about writing some code to
+ * generate the SQL for you: bust out raw SQL early and often.
  * 
- * (Because: raw SQL is comprehensible (non-magic); it's easily
- * debugged (since it can be cut-and-pasted to and from a query
- * browser); it avoids having to learn another language (the
- * language that maps from language-specific constructs to SQL); and
- * at some point you'll have to write raw SQL anyway (since, unless
- * you do a LOT of work, you aren't going to be able to reproduce
+ * (Because: raw SQL is comprehensible (non-magic); it's easily debugged (since
+ * it can be cut-and-pasted to and from a query browser); it avoids having to
+ * learn another language (the language that maps from language-specific
+ * constructs to SQL); and at some point you'll have to write raw SQL anyway
+ * (since, unless you do a LOT of work, you aren't going to be able to reproduce
  * some fancy SQL with your query language).
  * 
- * Note that there's very little difference between caching the PDO
- * connection yourself, and getting PDO to do it (for SQLite at
- * least)--see
+ * Note that there's very little difference between caching the PDO connection
+ * yourself, and getting PDO to do it (for SQLite at least)--see
  * 
  * http://netevil.org/blog/2005/sep/benchmarking-in-general
  * 
- * TODO write execute() method, and get it to handle SQLITE_BUSY
- * errors better.  See
+ * TODO write execute() method, and get it to handle SQLITE_BUSY errors better.
+ *
+ * See:
  * 
- * http://www.sqlite.org/c3ref/busy_handler.html
- * http://www.sqlite.org/c3ref/c_abort.html
+ *   * http://www.sqlite.org/c3ref/busy_handler.html
+ *   * http://www.sqlite.org/c3ref/c_abort.html
  * 
  * $error = $sth->errorInfo();
  * $error[1] == 5