Skip to content
This repository
Browse code

Updating doc blocks on Folder class and implementing a few small refa…

…ctors to make code simpler.
  • Loading branch information...
commit b33fdba6d9808703c008a40bf889298a633b7cdd 1 parent 23a62b4
Mark Story authored January 25, 2010
89  cake/libs/folder.php
@@ -28,8 +28,7 @@
28 28
 
29 29
 /**
30 30
  * Folder structure browser, lists folders and files.
31  
- *
32  
- * Long description for class
  31
+ * Provides an Object interface for Common directory related tasks.
33 32
  *
34 33
  * @package       cake
35 34
  * @subpackage    cake.cake.libs
@@ -45,7 +44,8 @@ class Folder extends Object {
45 44
 	var $path = null;
46 45
 
47 46
 /**
48  
- * Sortedness.
  47
+ * Sortedness. Whether or not list results
  48
+ * should be sorted by name.
49 49
  *
50 50
  * @var boolean
51 51
  * @access public
@@ -53,15 +53,15 @@ class Folder extends Object {
53 53
 	var $sort = false;
54 54
 
55 55
 /**
56  
- * mode to be used on create.
  56
+ * Mode to be used on create. Does nothing on windows platforms.
57 57
  *
58  
- * @var boolean
  58
+ * @var integer
59 59
  * @access public
60 60
  */
61 61
 	var $mode = 0755;
62 62
 
63 63
 /**
64  
- * holds messages from last method.
  64
+ * Holds messages from last method.
65 65
  *
66 66
  * @var array
67 67
  * @access private
@@ -69,7 +69,7 @@ class Folder extends Object {
69 69
 	var $__messages = array();
70 70
 
71 71
 /**
72  
- * holds errors from last method.
  72
+ * Holds errors from last method.
73 73
  *
74 74
  * @var array
75 75
  * @access private
@@ -77,7 +77,7 @@ class Folder extends Object {
77 77
 	var $__errors = false;
78 78
 
79 79
 /**
80  
- * holds array of complete directory paths.
  80
+ * Holds array of complete directory paths.
81 81
  *
82 82
  * @var array
83 83
  * @access private
@@ -85,7 +85,7 @@ class Folder extends Object {
85 85
 	var $__directories;
86 86
 
87 87
 /**
88  
- * holds array of complete file paths.
  88
+ * Holds array of complete file paths.
89 89
  *
90 90
  * @var array
91 91
  * @access private
@@ -148,7 +148,8 @@ function cd($path) {
148 148
  * Returns an array of the contents of the current directory.
149 149
  * The returned array holds two arrays: One of directories and one of files.
150 150
  *
151  
- * @param boolean $sort
  151
+ * @param boolean $sort Whether you want the results sorted, set this and the sort property
  152
+ *   to false to get unsorted results.
152 153
  * @param mixed $exceptions Either an array or boolean true will not grab dot files
153 154
  * @param boolean $fullPath True returns the full path
154 155
  * @return mixed Contents of current directory as an array, an empty array on failure
@@ -195,6 +196,7 @@ function read($sort = true, $exceptions = false, $fullPath = false) {
195 196
  * Returns an array of all matching files in current directory.
196 197
  *
197 198
  * @param string $pattern Preg_match pattern (Defaults to: .*)
  199
+ * @param boolean $sort Whether results should be sorted.
198 200
  * @return array Files that match given pattern
199 201
  * @access public
200 202
  */
@@ -207,6 +209,7 @@ function find($regexpPattern = '.*', $sort = false) {
207 209
  * Returns an array of all matching files in and below current directory.
208 210
  *
209 211
  * @param string $pattern Preg_match pattern (Defaults to: .*)
  212
+ * @param boolean $sort Whether results should be sorted.
210 213
  * @return array Files matching $pattern
211 214
  * @access public
212 215
  */
@@ -224,6 +227,7 @@ function findRecursive($pattern = '.*', $sort = false) {
224 227
  * Private helper function for findRecursive.
225 228
  *
226 229
  * @param string $pattern Pattern to match against
  230
+ * @param boolean $sort Whether results should be sorted.
227 231
  * @return array Files matching pattern
228 232
  * @access private
229 233
  */
@@ -254,23 +258,19 @@ function _findRecursive($pattern, $sort = false) {
254 258
  * @static
255 259
  */
256 260
 	function isWindowsPath($path) {
257  
-		if (preg_match('/^[A-Z]:\\\\/i', $path)) {
258  
-			return true;
259  
-		}
260  
-		return false;
  261
+		return (bool) preg_match('/^[A-Z]:\\\\/i', $path);
261 262
 	}
262 263
 
263 264
 /**
264 265
  * Returns true if given $path is an absolute path.
265 266
  *
266 267
  * @param string $path Path to check
267  
- * @return bool
  268
+ * @return bool true if path is absolute.
268 269
  * @access public
269 270
  * @static
270 271
  */
271 272
 	function isAbsolute($path) {
272  
-		$match = preg_match('/^\\//', $path) || preg_match('/^[A-Z]:\\\\/i', $path);
273  
-		return $match;
  273
+		return (bool) (preg_match('/^\\//', $path) || preg_match('/^[A-Z]:\\\\/i', $path));
274 274
 	}
275 275
 
276 276
 /**
@@ -294,10 +294,7 @@ function normalizePath($path) {
294 294
  * @static
295 295
  */
296 296
 	function correctSlashFor($path) {
297  
-		if (Folder::isWindowsPath($path)) {
298  
-			return '\\';
299  
-		}
300  
-		return '/';
  297
+		return (Folder::isWindowsPath($path)) ? '\\' : '/';
301 298
 	}
302 299
 
303 300
 /**
@@ -331,6 +328,7 @@ function addPathElement($path, $element) {
331 328
 /**
332 329
  * Returns true if the File is in a given CakePath.
333 330
  *
  331
+ * @param string $path The path to check.
334 332
  * @return bool
335 333
  * @access public
336 334
  */
@@ -344,6 +342,8 @@ function inCakePath($path = '') {
344 342
 /**
345 343
  * Returns true if the File is in given path.
346 344
  *
  345
+ * @param string $path The path to check that the current pwd() resides with in.
  346
+ * @param boolean $reverse
347 347
  * @return bool
348 348
  * @access public
349 349
  */
@@ -356,11 +356,7 @@ function inPath($path = '', $reverse = false) {
356 356
 		} else {
357 357
 			$return = preg_match('/^(.*)' . preg_quote($current, '/') . '(.*)/', $dir);
358 358
 		}
359  
-		if ($return == 1) {
360  
-			return true;
361  
-		} else {
362  
-			return false;
363  
-		}
  359
+		return (bool) $return;
364 360
 	}
365 361
 
366 362
 /**
@@ -368,7 +364,7 @@ function inPath($path = '', $reverse = false) {
368 364
  *
369 365
  * @param string $path The path to chmod
370 366
  * @param integer $mode octal value 0755
371  
- * @param boolean $recursive chmod recursively
  367
+ * @param boolean $recursive chmod recursively, set to false to only change the current directory.
372 368
  * @param array $exceptions array of files, directories to skip
373 369
  * @return boolean Returns TRUE on success, FALSE on failure
374 370
  * @access public
@@ -419,7 +415,7 @@ function chmod($path, $mode = false, $recursive = true, $exceptions = array()) {
419 415
  * Returns an array of nested directories and files in each directory
420 416
  *
421 417
  * @param string $path the directory path to build the tree from
422  
- * @param boolean $hidden return hidden files and directories
  418
+ * @param mixed $exceptions Array of files to exclude, defaults to excluding hidden files.
423 419
  * @param string $type either file or dir. null returns both files and directories
424 420
  * @return mixed array of nested directories and files in each directory
425 421
  * @access public
@@ -431,8 +427,8 @@ function tree($path, $exceptions = true, $type = null) {
431 427
 		$this->__directories = array($path);
432 428
 		$directories = array();
433 429
 
434  
-		if ($exceptions === false) {
435  
-			$exceptions = true;
  430
+		if ($hidden === false) {
  431
+			$hidden = true;
436 432
 		}
437 433
 		while (count($this->__directories)) {
438 434
 			$dir = array_pop($this->__directories);
@@ -454,20 +450,21 @@ function tree($path, $exceptions = true, $type = null) {
454 450
 /**
455 451
  * Private method to list directories and files in each directory
456 452
  *
457  
- * @param string $path
458  
- * @param = boolean $hidden
  453
+ * @param string $path The Path to read.
  454
+ * @param mixed $hidden Array of files to exclude from the read that will be performed.
459 455
  * @access private
460 456
  */
461  
-	function __tree($path, $exceptions) {
  457
+	function __tree($path, $hidden) {
462 458
 		if ($this->cd($path)) {
463  
-			list($dirs, $files) = $this->read(false, $exceptions, true);
  459
+			list($dirs, $files) = $this->read(false, $hidden, true);
464 460
 			$this->__directories = array_merge($this->__directories, $dirs);
465 461
 			$this->__files = array_merge($this->__files, $files);
466 462
 		}
467 463
 	}
468 464
 
469 465
 /**
470  
- * Create a directory structure recursively.
  466
+ * Create a directory structure recursively. Can be used to create
  467
+ * deep path structures like `/foo/bar/baz/shoe/horn`
471 468
  *
472 469
  * @param string $pathname The directory structure to create
473 470
  * @param integer $mode octal value 0755
@@ -507,7 +504,7 @@ function create($pathname, $mode = false) {
507 504
 	}
508 505
 
509 506
 /**
510  
- * Returns the size in bytes of this Folder.
  507
+ * Returns the size in bytes of this Folder and its contents.
511 508
  *
512 509
  * @param string $directory Path to directory
513 510
  * @return int size in bytes of current folder
@@ -544,7 +541,7 @@ function dirsize() {
544 541
 	}
545 542
 
546 543
 /**
547  
- * Recursively Remove directories if system allow.
  544
+ * Recursively Remove directories if the system allows.
548 545
  *
549 546
  * @param string $path Path of directory to delete
550 547
  * @return boolean Success
@@ -596,8 +593,15 @@ function delete($path = null) {
596 593
 /**
597 594
  * Recursive directory copy.
598 595
  *
599  
- * @param array $options (to, from, chmod, skip)
600  
- * @return bool
  596
+ * ### Options
  597
+ *
  598
+ * - `to` The directory to copy to.
  599
+ * - `from` The directory to copy from, this will cause a cd() to occur, changing the results of pwd().
  600
+ * - `chmod` The mode to copy the files/directories with.
  601
+ * - `skip` Files/directories to skip.
  602
+ *
  603
+ * @param mixed $options Either an array of options (see above) or a string of the destination directory.
  604
+ * @return bool Success
601 605
  * @access public
602 606
  */
603 607
 	function copy($options = array()) {
@@ -675,6 +679,13 @@ function copy($options = array()) {
675 679
 /**
676 680
  * Recursive directory move.
677 681
  *
  682
+ * ### Options
  683
+ *
  684
+ * - `to` The directory to copy to.
  685
+ * - `from` The directory to copy from, this will cause a cd() to occur, changing the results of pwd().
  686
+ * - `chmod` The mode to copy the files/directories with.
  687
+ * - `skip` Files/directories to skip.
  688
+ *
678 689
  * @param array $options (to, from, chmod, skip)
679 690
  * @return boolean Success
680 691
  * @access public
3  cake/libs/log/file_log.php
@@ -21,7 +21,8 @@
21 21
 	require LIBS . 'file.php';
22 22
 }
23 23
 /**
24  
- * File Storage stream for Logging
  24
+ * File Storage stream for Logging.  Writes logs to different files
  25
+ * based on the type of log it is.
25 26
  *
26 27
  * @package cake
27 28
  * @subpackage cake.cake.libs.log

0 notes on commit b33fdba

Please sign in to comment.
Something went wrong with that request. Please try again.