From 3248e34819937ba0082b675610a68a2c22087169 Mon Sep 17 00:00:00 2001
From: Kyle Robinson Young <kyle@dontkry.com>
Date: Mon, 14 Nov 2011 22:40:02 -0800
Subject: [PATCH] Add @link to File and Folder utilities

---
 lib/Cake/Utility/File.php   | 30 +++++++++++++++++++++++++++++-
 lib/Cake/Utility/Folder.php | 25 +++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/lib/Cake/Utility/File.php b/lib/Cake/Utility/File.php
index 6f3c2c02e..95fd62f44 100644
--- a/lib/Cake/Utility/File.php
+++ b/lib/Cake/Utility/File.php
@@ -80,6 +80,7 @@ class File {
  * @param string $path Path to file
  * @param boolean $create Create file if it does not exist (if true)
  * @param integer $mode Mode to apply to the folder holding the file
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File
  */
 	public function __construct($path, $create = false, $mode = 0755) {
 		$this->Folder = new Folder(dirname($path), $create, $mode);
@@ -102,6 +103,7 @@ class File {
  * Creates the File.
  *
  * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::create
  */
 	public function create() {
 		$dir = $this->Folder->pwd();
@@ -121,6 +123,7 @@ class File {
  * @param string $mode A valid 'fopen' mode string (r|w|a ...)
  * @param boolean $force If true then the file will be re-opened even if its already opened, otherwise it won't
  * @return boolean True on success, false on failure
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::open
  */
 	public function open($mode = 'r', $force = false) {
 		if (!$force && is_resource($this->handle)) {
@@ -147,6 +150,7 @@ class File {
  * @param string $mode A `fread` compatible mode.
  * @param boolean $force If true then the file will be re-opened even if its already opened, otherwise it won't
  * @return mixed string on success, false on failure
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::read
  */
 	public function read($bytes = false, $mode = 'rb', $force = false) {
 		if ($bytes === false && $this->lock === null) {
@@ -182,6 +186,7 @@ class File {
  * @param mixed $offset The $offset in bytes to seek. If set to false then the current offset is returned.
  * @param integer $seek PHP Constant SEEK_SET | SEEK_CUR | SEEK_END determining what the $offset is relative to
  * @return mixed True on success, false on failure (set mode), false on failure or integer offset on success (get mode)
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::offset
  */
 	public function offset($offset = false, $seek = SEEK_SET) {
 		if ($offset === false) {
@@ -202,6 +207,7 @@ class File {
  * @param string $data Data to prepare for writing.
  * @param boolean $forceWindows
  * @return string The with converted line endings.
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::prepare
  */
 	public static function prepare($data, $forceWindows = false) {
 		$lineBreak = "\n";
@@ -218,6 +224,7 @@ class File {
  * @param string $mode Mode of writing. {@link http://php.net/fwrite See fwrite()}.
  * @param string $force force the file to open
  * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::write
  */
 	public function write($data, $mode = 'w', $force = false) {
 		$success = false;
@@ -244,6 +251,7 @@ class File {
  * @param string $data Data to write
  * @param string $force force the file to open
  * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::append
  */
 	public function append($data, $force = false) {
 		return $this->write($data, 'a', $force);
@@ -253,6 +261,7 @@ class File {
  * Closes the current file if it is opened.
  *
  * @return boolean True if closing was successful or file was already closed, otherwise false
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::close
  */
 	public function close() {
 		if (!is_resource($this->handle)) {
@@ -265,6 +274,7 @@ class File {
  * Deletes the File.
  *
  * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::delete
  */
 	public function delete() {
 		clearstatcache();
@@ -282,6 +292,7 @@ class File {
  * Returns the File info.
  *
  * @return string The File extension
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::info
  */
 	public function info() {
 		if ($this->info == null) {
@@ -297,6 +308,7 @@ class File {
  * Returns the File extension.
  *
  * @return string The File extension
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::ext
  */
 	public function ext() {
 		if ($this->info == null) {
@@ -312,6 +324,7 @@ class File {
  * Returns the File name without extension.
  *
  * @return string The File name without extension.
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::name
  */
 	public function name() {
 		if ($this->info == null) {
@@ -331,6 +344,7 @@ class File {
  * @param string $name The name of the file to make safe if different from $this->name
  * @param string $ext The name of the extension to make safe if different from $this->ext
  * @return string $ext the extension of the file
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::safe
  */
 	public function safe($name = null, $ext = null) {
 		if (!$name) {
@@ -347,6 +361,7 @@ class File {
  *
  * @param mixed $maxsize in MB or true to force
  * @return string md5 Checksum {@link http://php.net/md5_file See md5_file()}
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::md5
  */
 	public function md5($maxsize = 5) {
 		if ($maxsize === true) {
@@ -365,6 +380,7 @@ class File {
  * Returns the full path of the File.
  *
  * @return string Full path to file
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::pwd
  */
 	public function pwd() {
 		if (is_null($this->path)) {
@@ -377,6 +393,7 @@ class File {
  * Returns true if the File exists.
  *
  * @return boolean true if it exists, false otherwise
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::exists
  */
 	public function exists() {
 		return (file_exists($this->path) && is_file($this->path));
@@ -386,6 +403,7 @@ class File {
  * Returns the "chmod" (permissions) of the File.
  *
  * @return string Permissions for the file
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::perms
  */
 	public function perms() {
 		if ($this->exists()) {
@@ -398,6 +416,7 @@ class File {
  * Returns the Filesize
  *
  * @return integer size of the file in bytes, or false in case of an error
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::size
  */
 	public function size() {
 		if ($this->exists()) {
@@ -410,6 +429,7 @@ class File {
  * Returns true if the File is writable.
  *
  * @return boolean true if its writable, false otherwise
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::writable
  */
 	public function writable() {
 		return is_writable($this->path);
@@ -419,6 +439,7 @@ class File {
  * Returns true if the File is executable.
  *
  * @return boolean true if its executable, false otherwise
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::executable
  */
 	public function executable() {
 		return is_executable($this->path);
@@ -428,6 +449,7 @@ class File {
  * Returns true if the File is readable.
  *
  * @return boolean true if file is readable, false otherwise
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::readable
  */
 	public function readable() {
 		return is_readable($this->path);
@@ -437,6 +459,7 @@ class File {
  * Returns the File's owner.
  *
  * @return integer the Fileowner
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::owner
  */
 	public function owner() {
 		if ($this->exists()) {
@@ -449,6 +472,7 @@ class File {
  * Returns the File's group.
  *
  * @return integer the Filegroup
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::group
  */
 	public function group() {
 		if ($this->exists()) {
@@ -461,6 +485,7 @@ class File {
  * Returns last access time.
  *
  * @return integer timestamp Timestamp of last access time
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::lastAccess
  */
 	public function lastAccess() {
 		if ($this->exists()) {
@@ -473,6 +498,7 @@ class File {
  * Returns last modified time.
  *
  * @return integer timestamp Timestamp of last modification
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::lastChange
  */
 	public function lastChange() {
 		if ($this->exists()) {
@@ -485,6 +511,7 @@ class File {
  * Returns the current folder.
  *
  * @return Folder Current folder
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::Folder
  */
 	public function &Folder() {
 		return $this->Folder;
@@ -495,7 +522,8 @@ class File {
  *
  * @param string $dest destination for the copy
  * @param boolean $overwrite Overwrite $dest if exists
- * @return boolean Succes
+ * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#File::copy
  */
 	public function copy($dest, $overwrite = true) {
 		if (!$this->exists() || is_file($dest) && !$overwrite) {
diff --git a/lib/Cake/Utility/Folder.php b/lib/Cake/Utility/Folder.php
index e797d4417..fd1cdd160 100644
--- a/lib/Cake/Utility/Folder.php
+++ b/lib/Cake/Utility/Folder.php
@@ -81,6 +81,7 @@ class Folder {
  * @param string $path Path to folder
  * @param boolean $create Create folder if not found
  * @param mixed $mode Mode (CHMOD) to apply to created folder, false to ignore
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder
  */
 	public function __construct($path = false, $create = false, $mode = false) {
 		if (empty($path)) {
@@ -105,6 +106,7 @@ class Folder {
  * Return current path.
  *
  * @return string Current path
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::pwd
  */
 	public function pwd() {
 		return $this->path;
@@ -115,6 +117,7 @@ class Folder {
  *
  * @param string $path Path to the directory to change to
  * @return string The new path. Returns false on failure
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::cd
  */
 	public function cd($path) {
 		$path = $this->realpath($path);
@@ -133,6 +136,7 @@ class Folder {
  * @param mixed $exceptions Either an array or boolean true will not grab dot files
  * @param boolean $fullPath True returns the full path
  * @return mixed Contents of current directory as an array, an empty array on failure
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::read
  */
 	public function read($sort = true, $exceptions = false, $fullPath = false) {
 		$dirs = $files = array();
@@ -181,6 +185,7 @@ class Folder {
  * @param string $regexpPattern Preg_match pattern (Defaults to: .*)
  * @param boolean $sort Whether results should be sorted.
  * @return array Files that match given pattern
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::find
  */
 	public function find($regexpPattern = '.*', $sort = false) {
 		list($dirs, $files) = $this->read($sort);
@@ -193,6 +198,7 @@ class Folder {
  * @param string $pattern Preg_match pattern (Defaults to: .*)
  * @param boolean $sort Whether results should be sorted.
  * @return array Files matching $pattern
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::findRecursive
  */
 	public function findRecursive($pattern = '.*', $sort = false) {
 		if (!$this->pwd()) {
@@ -234,6 +240,7 @@ class Folder {
  *
  * @param string $path Path to check
  * @return boolean true if windows path, false otherwise
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::isWindowsPath
  */
 	public static function isWindowsPath($path) {
 		return (preg_match('/^[A-Z]:\\\\/i', $path) || substr($path, 0, 2) == '\\\\');
@@ -244,6 +251,7 @@ class Folder {
  *
  * @param string $path Path to check
  * @return boolean true if path is absolute.
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::isAbsolute
  */
 	public static function isAbsolute($path) {
 		return !empty($path) && ($path[0] === '/' || preg_match('/^[A-Z]:\\\\/i', $path) || substr($path, 0, 2) == '\\\\');
@@ -254,6 +262,7 @@ class Folder {
  *
  * @param string $path Path to check
  * @return string Set of slashes ("\\" or "/")
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::normalizePath
  */
 	public static function normalizePath($path) {
 		return Folder::correctSlashFor($path);
@@ -264,6 +273,7 @@ class Folder {
  *
  * @param string $path Path to check
  * @return string Set of slashes ("\\" or "/")
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::correctSlashFor
  */
 	public static function correctSlashFor($path) {
 		return (Folder::isWindowsPath($path)) ? '\\' : '/';
@@ -274,6 +284,7 @@ class Folder {
  *
  * @param string $path Path to check
  * @return string Path with ending slash
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::slashTerm
  */
 	public static function slashTerm($path) {
 		if (Folder::isSlashTerm($path)) {
@@ -288,6 +299,7 @@ class Folder {
  * @param string $path Path
  * @param string $element Element to and at end of path
  * @return string Combined path
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::addPathElement
  */
 	public static function addPathElement($path, $element) {
 		return rtrim($path, DS) . DS . $element;
@@ -298,6 +310,7 @@ class Folder {
  *
  * @param string $path The path to check.
  * @return boolean
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::inCakePath
  */
 	public function inCakePath($path = '') {
 		$dir = substr(Folder::slashTerm(ROOT), 0, -1);
@@ -312,6 +325,7 @@ class Folder {
  * @param string $path The path to check that the current pwd() resides with in.
  * @param boolean $reverse
  * @return boolean
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::inPath
  */
 	public function inPath($path = '', $reverse = false) {
 		$dir = Folder::slashTerm($path);
@@ -333,6 +347,7 @@ class Folder {
  * @param boolean $recursive chmod recursively, set to false to only change the current directory.
  * @param array $exceptions array of files, directories to skip
  * @return boolean Returns TRUE on success, FALSE on failure
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::chmod
  */
 	public function chmod($path, $mode = false, $recursive = true, $exceptions = array()) {
 		if (!$mode) {
@@ -383,6 +398,7 @@ class Folder {
  * @param mixed $exceptions Array of files to exclude, defaults to excluding hidden files.
  * @param string $type either file or dir. null returns both files and directories
  * @return mixed array of nested directories and files in each directory
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::tree
  */
 	public function tree($path = null, $exceptions = true, $type = null) {
 		if ($path == null) {
@@ -449,6 +465,7 @@ class Folder {
  * @param string $pathname The directory structure to create
  * @param integer $mode octal value 0755
  * @return boolean Returns TRUE on success, FALSE on failure
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::create
  */
 	public function create($pathname, $mode = false) {
 		if (is_dir($pathname) || empty($pathname)) {
@@ -487,6 +504,7 @@ class Folder {
  * Returns the size in bytes of this Folder and its contents.
  *
  * @return integer size in bytes of current folder
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::dirsize
  */
 	public function dirsize() {
 		$size = 0;
@@ -523,6 +541,7 @@ class Folder {
  *
  * @param string $path Path of directory to delete
  * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::delete
  */
 	public function delete($path = null) {
 		if (!$path) {
@@ -579,6 +598,7 @@ class Folder {
  *
  * @param mixed $options Either an array of options (see above) or a string of the destination directory.
  * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::copy
  */
 	public function copy($options = array()) {
 		if (!$this->pwd()) {
@@ -664,6 +684,7 @@ class Folder {
  *
  * @param array $options (to, from, chmod, skip)
  * @return boolean Success
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::move
  */
 	public function move($options) {
 		$to = null;
@@ -688,6 +709,7 @@ class Folder {
  * get messages from latest method
  *
  * @return array
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::messages
  */
 	public function messages() {
 		return $this->_messages;
@@ -697,6 +719,7 @@ class Folder {
  * get error from latest method
  *
  * @return array
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::errors
  */
 	public function errors() {
 		return $this->_errors;
@@ -707,6 +730,7 @@ class Folder {
  *
  * @param string $path Path to resolve
  * @return string The resolved path
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::realpath
  */
 	public function realpath($path) {
 		$path = str_replace('/', DS, trim($path));
@@ -747,6 +771,7 @@ class Folder {
  *
  * @param string $path Path to check
  * @return boolean true if path ends with slash, false otherwise
+ * @link http://book.cakephp.org/2.0/en/core-utility-libraries/file-folder.html#Folder::isSlashTerm
  */
 	public static function isSlashTerm($path) {
 		$lastChar = $path[strlen($path) - 1];