注释规范

library/think/db/Builder.php

@@ -72,8 +72,8 @@ abstract class Builder
     /**
      * 数据分析
      * @access protected
-     * @param array $data 数据
-     * @param array $options 查询参数
+     * @param array     $data 数据
+     * @param array     $options 查询参数
      * @return array
      */
     protected function parseData($data, $options)
@@ -213,7 +213,8 @@ abstract class Builder
     /**
      * 生成查询条件SQL
      * @access public
-     * @param mixed $where
+     * @param mixed     $where
+     * @param string    $table
      * @return string
      */
     public function buildWhere($where, $table)
@@ -361,8 +362,8 @@ abstract class Builder
     /**
      * 日期时间条件解析
      * @access protected
-     * @param string $value
-     * @param string $key
+     * @param string    $value
+     * @param string    $key
      * @return string
      */
     protected function parseDateTime($value, $key)
@@ -563,9 +564,9 @@ abstract class Builder
     /**
      * 生成insert SQL
      * @access public
-     * @param array $data 数据
-     * @param array $options 表达式
-     * @param bool $replace 是否replace
+     * @param array     $data 数据
+     * @param array     $options 表达式
+     * @param bool      $replace 是否replace
      * @return string
      */
     public function insert(array $data, $options = [], $replace = false)
@@ -594,8 +595,8 @@ abstract class Builder
     /**
      * 生成insertall SQL
      * @access public
-     * @param array $dataSet 数据集
-     * @param array $options 表达式
+     * @param array     $dataSet 数据集
+     * @param array     $options 表达式
      * @return string
      */
     public function insertAll($dataSet, $options)
@@ -640,9 +641,9 @@ abstract class Builder
     /**
      * 生成slectinsert SQL
      * @access public
-     * @param array $fields 数据
-     * @param string $table 数据表
-     * @param array $options 表达式
+     * @param array     $fields 数据
+     * @param string    $table 数据表
+     * @param array     $options 表达式
      * @return string
      */
     public function selectInsert($fields, $table, $options)
@@ -659,8 +660,8 @@ abstract class Builder
     /**
      * 生成update SQL
      * @access public
-     * @param array $fields 数据
-     * @param array $options 表达式
+     * @param array     $fields 数据
+     * @param array     $options 表达式
      * @return string
      */
     public function update($data, $options)

library/think/db/Connection.php

@@ -138,8 +138,8 @@ abstract class Connection
     /**
      * 调用Query类的查询方法
      * @access public
-     * @param string $method 方法名称
-     * @param array $args 调用参数
+     * @param string    $method 方法名称
+     * @param array     $args 调用参数
      * @return mixed
      */
     public function __call($method, $args)
@@ -219,8 +219,8 @@ abstract class Connection
     /**
      * 设置数据库的配置参数
      * @access public
-     * @param string $config 配置名称
-     * @param mixed $value 配置值
+     * @param string    $config 配置名称
+     * @param mixed     $value 配置值
      * @return void
      */
     public function setConfig($config, $value)
@@ -231,9 +231,9 @@ abstract class Connection
     /**
      * 连接数据库方法
      * @access public
-     * @param array $config 连接参数
-     * @param integer $linkNum 连接序号
-     * @param array|bool $autoConnection 是否自动连接主数据库（用于分布式）
+     * @param array         $config 连接参数
+     * @param integer       $linkNum 连接序号
+     * @param array|bool    $autoConnection 是否自动连接主数据库（用于分布式）
      * @return PDO
      * @throws Exception
      */
@@ -314,10 +314,10 @@ abstract class Connection
     /**
      * 执行查询 返回数据集
      * @access public
-     * @param string $sql sql指令
-     * @param array $bind 参数绑定
-     * @param boolean $master 是否在主服务器读操作
-     * @param bool|string $class 指定返回的数据集对象
+     * @param string        $sql sql指令
+     * @param array         $bind 参数绑定
+     * @param boolean       $master 是否在主服务器读操作
+     * @param bool|string   $class 指定返回的数据集对象
      * @return mixed
      * @throws BindParamException
      * @throws PDOException
@@ -358,10 +358,10 @@ abstract class Connection
     /**
      * 执行语句
      * @access public
-     * @param string $sql sql指令
-     * @param array $bind 参数绑定
-     * @param boolean $getLastInsID 是否获取自增ID
-     * @param string $sequence 自增序列名
+     * @param string        $sql sql指令
+     * @param array         $bind 参数绑定
+     * @param boolean       $getLastInsID 是否获取自增ID
+     * @param string        $sequence 自增序列名
      * @return int
      * @throws BindParamException
      * @throws PDOException
@@ -409,8 +409,8 @@ abstract class Connection
     /**
      * 根据参数绑定组装最终的SQL语句 便于调试
      * @access public
-     * @param string $sql 带参数绑定的sql语句
-     * @param array $bind 参数绑定列表
+     * @param string    $sql 带参数绑定的sql语句
+     * @param array     $bind 参数绑定列表
      * @return string
      */
     public function getRealSql($sql, array $bind = [])
@@ -463,8 +463,8 @@ abstract class Connection
     /**
      * 获得数据集
      * @access protected
-     * @param bool|string $class true 返回PDOStatement 字符串用于指定返回的类名
-     * @param bool $procedure 是否存储过程
+     * @param bool|string   $class true 返回PDOStatement 字符串用于指定返回的类名
+     * @param bool          $procedure 是否存储过程
      * @return mixed
      */
     protected function getResult($class = '', $procedure = false)
@@ -777,9 +777,9 @@ abstract class Connection
     /**
      * 触发SQL事件
      * @access protected
-     * @param string $sql SQL语句
-     * @param float $runtime SQL运行时间
-     * @param mixed $explain SQL分析
+     * @param string    $sql SQL语句
+     * @param float     $runtime SQL运行时间
+     * @param mixed     $explain SQL分析
      * @return bool
      */
     protected function trigger($sql, $runtime, $explain = [])

library/think/db/Query.php

@@ -67,8 +67,8 @@ class Query
     /**
      * 利用__call方法实现一些特殊的Model方法
      * @access public
-     * @param string $method 方法名称
-     * @param array $args 调用参数
+     * @param string    $method 方法名称
+     * @param array     $args 调用参数
      * @return mixed
      * @throws DbException
      * @throws Exception
@@ -176,11 +176,11 @@ class Query
     /**
      * 执行查询 返回数据集
      * @access public
-     * @param string $sql sql指令
-     * @param array $bind 参数绑定
-     * @param boolean $fetch 不执行只是获取SQL
-     * @param boolean $master 是否在主服务器读操作
-     * @param bool|string $class 指定返回的数据集对象
+     * @param string        $sql sql指令
+     * @param array         $bind 参数绑定
+     * @param boolean       $fetch 不执行只是获取SQL
+     * @param boolean       $master 是否在主服务器读操作
+     * @param bool|string   $class 指定返回的数据集对象
      * @return mixed
      * @throws BindParamException
      * @throws PDOException
@@ -193,11 +193,11 @@ class Query
     /**
      * 执行语句
      * @access public
-     * @param string $sql sql指令
-     * @param array $bind 参数绑定
-     * @param boolean $fetch 不执行只是获取SQL
-     * @param boolean $getLastInsID 是否获取自增ID
-     * @param boolean $sequence 自增序列名
+     * @param string    $sql sql指令
+     * @param array     $bind 参数绑定
+     * @param boolean   $fetch 不执行只是获取SQL
+     * @param boolean   $getLastInsID 是否获取自增ID
+     * @param boolean   $sequence 自增序列名
      * @return int
      * @throws BindParamException
      * @throws PDOException
@@ -296,9 +296,9 @@ class Query
     /**
      * 得到分表的的数据表名
      * @access public
-     * @param array $data 操作的数据
-     * @param string $field 分表依据的字段
-     * @param array $rule 分表规则
+     * @param array     $data 操作的数据
+     * @param string    $field 分表依据的字段
+     * @param array     $rule 分表规则
      * @return string
      */
     public function getPartitionTableName($data, $field, $rule = [])
@@ -372,8 +372,8 @@ class Query
     /**
      * 得到某个字段的值
      * @access public
-     * @param string $field 字段名
-     * @param mixed $default 默认值
+     * @param string    $field 字段名
+     * @param mixed     $default 默认值
      * @return mixed
      */
     public function value($field, $default = null)
@@ -408,8 +408,8 @@ class Query
     /**
      * 得到某个列的数组
      * @access public
-     * @param string $field 字段名 多个字段用逗号分隔
-     * @param string $key 索引
+     * @param string    $field 字段名 多个字段用逗号分隔
+     * @param string    $key 索引
      * @return array
      */
     public function column($field, $key = '')
@@ -525,8 +525,8 @@ class Query
      * 设置记录的某个字段值
      * 支持使用数据库字段和方法
      * @access public
-     * @param string|array $field 字段名
-     * @param mixed $value 字段值
+     * @param string|array  $field 字段名
+     * @param mixed         $value 字段值
      * @return integer
      */
     public function setField($field, $value = '')
@@ -542,9 +542,9 @@ class Query
     /**
      * 字段值(延迟)增长
      * @access public
-     * @param string $field 字段名
-     * @param integer $step 增长值
-     * @param integer $lazyTime 延时时间(s)
+     * @param string    $field 字段名
+     * @param integer   $step 增长值
+     * @param integer   $lazyTime 延时时间(s)
      * @return integer|true
      * @throws Exception
      */
@@ -569,9 +569,9 @@ class Query
     /**
      * 字段值（延迟）减少
      * @access public
-     * @param string $field 字段名
-     * @param integer $step 减少值
-     * @param integer $lazyTime 延时时间(s)
+     * @param string    $field 字段名
+     * @param integer   $step 减少值
+     * @param integer   $lazyTime 延时时间(s)
      * @return integer|true
      * @throws Exception
      */
@@ -597,9 +597,9 @@ class Query
      * 延时更新检查 返回false表示需要延时
      * 否则返回实际写入的数值
      * @access public
-     * @param string $guid 写入标识
-     * @param integer $step 写入步进值
-     * @param integer $lazyTime 延时时间(s)
+     * @param string    $guid 写入标识
+     * @param integer   $step 写入步进值
+     * @param integer   $lazyTime 延时时间(s)
      * @return false|integer
      */
     protected function lazyWrite($guid, $step, $lazyTime)
@@ -628,9 +628,9 @@ class Query
     /**
      * 查询SQL组装 join
      * @access public
-     * @param mixed $join 关联的表名
-     * @param mixed $condition 条件
-     * @param string $type JOIN类型
+     * @param mixed     $join 关联的表名
+     * @param mixed     $condition 条件
+     * @param string    $type JOIN类型
      * @return $this
      */
     public function join($join, $condition = null, $type = 'INNER')
@@ -681,8 +681,8 @@ class Query
     /**
      * 查询SQL组装 union
      * @access public
-     * @param mixed $union
-     * @param boolean $all
+     * @param mixed     $union
+     * @param boolean   $all
      * @return $this
      */
     public function union($union, $all = false)
@@ -700,11 +700,11 @@ class Query
     /**
      * 指定查询字段 支持字段排除和指定数据表
      * @access public
-     * @param mixed $field
-     * @param boolean $except 是否排除
-     * @param string $tableName 数据表名
-     * @param string $prefix 字段前缀
-     * @param string $alias 别名前缀
+     * @param mixed     $field
+     * @param boolean   $except 是否排除
+     * @param string    $tableName 数据表名
+     * @param string    $prefix 字段前缀
+     * @param string    $alias 别名前缀
      * @return $this
      */
     public function field($field, $except = false, $tableName = '', $prefix = '', $alias = '')
@@ -745,10 +745,10 @@ class Query
     /**
      * 指定JOIN查询字段
      * @access public
-     * @param string|array $table 数据表
-     * @param string|array $field 查询字段
-     * @param string|array $on JOIN条件
-     * @param string $type JOIN类型
+     * @param string|array  $table 数据表
+     * @param string|array  $field 查询字段
+     * @param string|array  $on JOIN条件
+     * @param string        $type JOIN类型
      * @return $this
      */
     public function view($join, $field = null, $on = null, $type = 'INNER')
@@ -796,9 +796,9 @@ class Query
     /**
      * 设置分表规则
      * @access public
-     * @param array $data 操作的数据
-     * @param string $field 分表依据的字段
-     * @param array $rule 分表规则
+     * @param array     $data 操作的数据
+     * @param string    $field 分表依据的字段
+     * @param array     $rule 分表规则
      * @return $this
      */
     public function partition($data, $field, $rule = [])
@@ -810,9 +810,9 @@ class Query
     /**
      * 指定AND查询条件
      * @access public
-     * @param mixed $field 查询字段
-     * @param mixed $op 查询表达式
-     * @param mixed $condition 查询条件
+     * @param mixed     $field 查询字段
+     * @param mixed     $op 查询表达式
+     * @param mixed     $condition 查询条件
      * @return $this
      */
     public function where($field, $op = null, $condition = null)
@@ -826,9 +826,9 @@ class Query
     /**
      * 指定OR查询条件
      * @access public
-     * @param mixed $field 查询字段
-     * @param mixed $op 查询表达式
-     * @param mixed $condition 查询条件
+     * @param mixed     $field 查询字段
+     * @param mixed     $op 查询表达式
+     * @param mixed     $condition 查询条件
      * @return $this
      */
     public function whereOr($field, $op = null, $condition = null)
@@ -842,9 +842,9 @@ class Query
     /**
      * 指定XOR查询条件
      * @access public
-     * @param mixed $field 查询字段
-     * @param mixed $op 查询表达式
-     * @param mixed $condition 查询条件
+     * @param mixed     $field 查询字段
+     * @param mixed     $op 查询表达式
+     * @param mixed     $condition 查询条件
      * @return $this
      */
     public function whereXor($field, $op = null, $condition = null)
@@ -858,11 +858,11 @@ class Query
     /**
      * 分析查询表达式
      * @access public
-     * @param string $logic 查询逻辑 and or xor
+     * @param string                $logic 查询逻辑 and or xor
      * @param string|array|\Closure $field 查询字段
-     * @param mixed $op 查询表达式
-     * @param mixed $condition 查询条件
-     * @param array $param 查询参数
+     * @param mixed                 $op 查询表达式
+     * @param mixed                 $condition 查询条件
+     * @param array                 $param 查询参数
      * @return void
      */
     protected function parseWhereExp($logic, $field, $op, $condition, $param = [])
@@ -944,9 +944,9 @@ class Query
 
     /**
      * 分页查询
-     * @param int|null $listRows 每页数量
-     * @param bool $simple 简洁模式
-     * @param array $config 配置参数
+     * @param int|null  $listRows 每页数量
+     * @param bool      $simple 简洁模式
+     * @param array     $config 配置参数
      *                      page:当前页,
      *                      path:url路径,
      *                      query:url额外参数,
@@ -1013,8 +1013,8 @@ class Query
     /**
      * 指定排序 order('id','desc') 或者 order(['id'=>'desc','create_time'=>'desc'])
      * @access public
-     * @param string|array $field 排序字段
-     * @param string $order 排序
+     * @param string|array  $field 排序字段
+     * @param string        $order 排序
      * @return $this
      */
     public function order($field, $order = null)
@@ -1043,8 +1043,8 @@ class Query
     /**
      * 查询缓存
      * @access public
-     * @param mixed $key
-     * @param integer $expire
+     * @param mixed     $key 缓存key
+     * @param integer   $expire 缓存有效期
      * @return $this
      */
     public function cache($key = true, $expire = null)
@@ -1344,9 +1344,9 @@ class Query
     /**
      * 参数绑定
      * @access public
-     * @param mixed $key 参数名
-     * @param mixed $value 绑定变量值
-     * @param integer $type 绑定类型
+     * @param mixed     $key 参数名
+     * @param mixed     $value 绑定变量值
+     * @param integer   $type 绑定类型
      * @return $this
      */
     public function bind($key, $value = false, $type = PDO::PARAM_STR)
@@ -1520,8 +1520,8 @@ class Query
     /**
      * 把主键值转换为查询条件 支持复合主键
      * @access public
-     * @param array|string $data 主键数据
-     * @param mixed $options 表达式参数
+     * @param array|string  $data 主键数据
+     * @param mixed         $options 表达式参数
      * @return void
      * @throws Exception
      */
@@ -1565,10 +1565,10 @@ class Query
     /**
      * 插入记录
      * @access public
-     * @param mixed $data 数据
-     * @param boolean $replace 是否replace
-     * @param boolean $getLastInsID 是否获取自增ID
-     * @param string $sequence 自增序列名
+     * @param mixed     $data 数据
+     * @param boolean   $replace 是否replace
+     * @param boolean   $getLastInsID 是否获取自增ID
+     * @param string    $sequence 自增序列名
      * @return integer|string
      */
     public function insert(array $data, $replace = false, $getLastInsID = false, $sequence = null)
@@ -1589,9 +1589,9 @@ class Query
     /**
      * 插入记录并获取自增ID
      * @access public
-     * @param mixed $data 数据
-     * @param boolean $replace 是否replace
-     * @param string $sequence 自增序列名
+     * @param mixed     $data 数据
+     * @param boolean   $replace 是否replace
+     * @param string    $sequence 自增序列名
      * @return integer|string
      */
     public function insertGetId(array $data, $replace = false, $sequence = null)
@@ -1626,8 +1626,8 @@ class Query
     /**
      * 通过Select方式插入记录
      * @access public
-     * @param string $fields 要插入的数据表字段名
-     * @param string $table 要插入的数据表名
+     * @param string    $fields 要插入的数据表字段名
+     * @param string    $table 要插入的数据表名
      * @return integer|string
      * @throws PDOException
      */
@@ -1895,9 +1895,9 @@ class Query
     /**
      * 分批数据返回处理
      * @access public
-     * @param integer $count 每次处理的数据数量
-     * @param callable $callback 处理回调方法
-     * @param string $column 分批处理的字段名
+     * @param integer   $count 每次处理的数据数量
+     * @param callable  $callback 处理回调方法
+     * @param string    $column 分批处理的字段名
      * @return boolean
      */
     public function chunk($count, $callback, $column = null)