From 1f7d270dfbd4a1a38294eb7d3db17dc2fde7ba9f Mon Sep 17 00:00:00 2001
From: Tim Otten <totten@civicrm.org>
Date: Mon, 9 Jan 2017 16:09:47 -0800
Subject: [PATCH] CRM_Utils_SQL_Select - Add docblocks

---
 CRM/Utils/SQL/Select.php | 43 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/CRM/Utils/SQL/Select.php b/CRM/Utils/SQL/Select.php
index 24ca2587d5..dbedf5b122 100644
--- a/CRM/Utils/SQL/Select.php
+++ b/CRM/Utils/SQL/Select.php
@@ -340,6 +340,9 @@ class CRM_Utils_SQL_Select implements ArrayAccess {
    * @param array|string $keys
    *   Key name, or an array of key-value pairs.
    * @param null|mixed $value
+   *   The new value of the parameter.
+   *   Values may be strings, ints, or arrays thereof -- provided that the
+   *   SQL query uses appropriate prefix (e.g. "@", "!", "#").
    * @return \CRM_Utils_SQL_Select
    */
   public function param($keys, $value = NULL) {
@@ -459,7 +462,7 @@ class CRM_Utils_SQL_Select implements ArrayAccess {
   /**
    * Given a string like "field_name = @value", replace "@value" with an escaped SQL string
    *
-   * @param $expr SQL expression
+   * @param string $expr SQL expression
    * @param null|array $args a list of values to insert into the SQL expression; keys are prefix-coded:
    *   prefix '@' => escape SQL
    *   prefix '#' => literal number, skip escaping but do validation
@@ -589,14 +592,52 @@ class CRM_Utils_SQL_Select implements ArrayAccess {
     return isset($this->params[$offset]);
   }
 
+  /**
+   * Get the value of a SQL parameter.
+   *
+   * @code
+   *   $select['cid'] = 123;
+   *   $select->where('contact.id = #cid');
+   *   echo $select['cid'];
+   * @endCode
+   *
+   * @param string $offset
+   * @return mixed
+   * @see param()
+   * @see ArrayAccess::offsetGet
+   */
   public function offsetGet($offset) {
     return $this->params[$offset];
   }
 
+  /**
+   * Set the value of a SQL parameter.
+   *
+   * @code
+   *   $select['cid'] = 123;
+   *   $select->where('contact.id = #cid');
+   *   echo $select['cid'];
+   * @endCode
+   *
+   * @param string $offset
+   * @param mixed $value
+   *   The new value of the parameter.
+   *   Values may be strings, ints, or arrays thereof -- provided that the
+   *   SQL query uses appropriate prefix (e.g. "@", "!", "#").
+   * @see param()
+   * @see ArrayAccess::offsetSet
+   */
   public function offsetSet($offset, $value) {
     $this->param($offset, $value);
   }
 
+  /**
+   * Unset the value of a SQL parameter.
+   *
+   * @param string $offset
+   * @see param()
+   * @see ArrayAccess::offsetUnset
+   */
   public function offsetUnset($offset) {
     unset($this->params[$offset]);
   }
-- 
2.25.1