From: skodak <skodak>
Date: Thu, 21 May 2009 09:37:21 +0000 (+0000)
Subject: MDL-18111 improving file api comments and docs
X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=4cd9dfda7bd0517aff0e7a557fad83cac3c14025;p=moodle.git

MDL-18111 improving file api comments and docs
---

diff --git a/lib/file/file_info.php b/lib/file/file_info.php
index c4ccd63449..5fad0a1908 100644
--- a/lib/file/file_info.php
+++ b/lib/file/file_info.php
@@ -60,8 +60,8 @@ abstract class file_info {
     public abstract function is_directory();
 
     /**
-     * Does this node have children?
-     * @return bool
+     * Returns list of children.
+     * @return array of file_info instances
      */
     public abstract function get_children();
 
@@ -88,7 +88,7 @@ abstract class file_info {
     }
 
     /**
-     * Returns download url for
+     * Returns file download url
      * @param bool $forcedownload
      * @param bool $htts force https
      * @return string url
diff --git a/lib/file/file_info_course.php b/lib/file/file_info_course.php
index 056963ce31..00bd4918a5 100644
--- a/lib/file/file_info_course.php
+++ b/lib/file/file_info_course.php
@@ -37,6 +37,12 @@ class file_info_course extends file_info {
         $this->course   = $course;
     }
 
+    /**
+     * Returns list of standard virtual file/directory identification.
+     * The difference from stored_file parameters is that null values
+     * are allowed in all fields
+     * @return array with keys contextid, filearea, itemid, filepath and filename
+     */
     public function get_params() {
         return array('contextid'=>$this->context->id,
                      'filearea' =>null,
@@ -49,14 +55,26 @@ class file_info_course extends file_info {
         return ($this->course->id == SITEID) ? get_string('frontpage', 'admin') : format_string($this->course->fullname);
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return false;
     }
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public function is_directory() {
         return true;
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         $children = array();
 
@@ -88,11 +106,13 @@ class file_info_course extends file_info {
 
         return $children;
     }
-    
+
     /**
-     * TODO error checking if get_parent_contextid() returns false
+     * Returns parent file_info instance
+     * @return file_info or null for root
      */
     public function get_parent() {
+        //TODO: error checking if get_parent_contextid() returns false
         $pcid = get_parent_contextid($this->context);
         $parent = get_context_instance_by_id($pcid);
         return $this->browser->get_file_info($parent);
diff --git a/lib/file/file_info_coursecat.php b/lib/file/file_info_coursecat.php
index 57e6de2121..97f7180e75 100644
--- a/lib/file/file_info_coursecat.php
+++ b/lib/file/file_info_coursecat.php
@@ -36,6 +36,12 @@ class file_info_coursecat extends file_info {
         $this->category = $category;
     }
 
+    /**
+     * Returns list of standard virtual file/directory identification.
+     * The difference from stored_file parameters is that null values
+     * are allowed in all fields
+     * @return array with keys contextid, filearea, itemid, filepath and filename
+     */
     public function get_params() {
         return array('contextid'=>$this->context->id,
                      'filearea' =>null,
@@ -44,18 +50,34 @@ class file_info_coursecat extends file_info {
                      'filename' =>null);
     }
 
+    /**
+     * Returns localised visible name.
+     * @return string
+     */
     public function get_visible_name() {
         return format_string($this->category->name);
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return false;
     }
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public function is_directory() {
         return true;
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         global $DB;
 
@@ -90,6 +112,10 @@ class file_info_coursecat extends file_info {
         return $children;
     }
 
+    /**
+     * Returns parent file_info instance
+     * @return file_info or null for root
+     */
     public function get_parent() {
         $cid = get_parent_contextid($this->context);
         $parent = get_context_instance_by_id($cid);
diff --git a/lib/file/file_info_coursefile.php b/lib/file/file_info_coursefile.php
index 6ddacadce4..0d1073f97e 100644
--- a/lib/file/file_info_coursefile.php
+++ b/lib/file/file_info_coursefile.php
@@ -35,6 +35,12 @@ class file_info_coursefile extends file_info_stored {
         parent::__construct($browser, $context, $storedfile, $urlbase, get_string('coursefiles'), false, true, true, false);
     }
 
+    /**
+     * Returns file download url
+     * @param bool $forcedownload
+     * @param bool $htts force https
+     * @return string url
+     */
     public function get_url($forcedownload=false, $https=false) {
         global $CFG;
 
@@ -55,6 +61,10 @@ class file_info_coursefile extends file_info_stored {
         return file_encode_url($this->urlbase, $path, $forcedownload, $https);
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         if (!$this->lf->is_directory()) {
             return array();
diff --git a/lib/file/file_info_coursesection.php b/lib/file/file_info_coursesection.php
index d3ef0cff1f..d42f1ce282 100644
--- a/lib/file/file_info_coursesection.php
+++ b/lib/file/file_info_coursesection.php
@@ -36,6 +36,12 @@ class file_info_coursesection extends file_info {
         $this->course = $course;
     }
 
+    /**
+     * Returns list of standard virtual file/directory identification.
+     * The difference from stored_file parameters is that null values
+     * are allowed in all fields
+     * @return array with keys contextid, filearea, itemid, filepath and filename
+     */
     public function get_params() {
         return array('contextid'=>$this->context->id,
                      'filearea' =>'course_section',
@@ -44,6 +50,10 @@ class file_info_coursesection extends file_info {
                      'filename' =>null);
     }
 
+    /**
+     * Returns localised visible name.
+     * @return string
+     */
     public function get_visible_name() {
         $format = $this->course->format;
         $sectionsname = get_string("coursesectionsummaries");
@@ -51,14 +61,26 @@ class file_info_coursesection extends file_info {
         return $sectionsname;
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return false;
     }
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public function is_directory() {
         return true;
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         global $DB;
 
@@ -74,6 +96,10 @@ class file_info_coursesection extends file_info {
         return $children;
     }
 
+    /**
+     * Returns parent file_info instance
+     * @return file_info or null for root
+     */
     public function get_parent() {
         return $this->browser->get_file_info($this->context);
     }
diff --git a/lib/file/file_info_module.php b/lib/file/file_info_module.php
index 375b2da22e..5de584afc5 100644
--- a/lib/file/file_info_module.php
+++ b/lib/file/file_info_module.php
@@ -41,6 +41,12 @@ class file_info_module extends file_info {
         $this->areas  = $areas;
     }
 
+    /**
+     * Returns list of standard virtual file/directory identification.
+     * The difference from stored_file parameters is that null values
+     * are allowed in all fields
+     * @return array with keys contextid, filearea, itemid, filepath and filename
+     */
     public function get_params() {
         return array('contextid'=>$this->context->id,
                      'filearea' =>null,
@@ -49,18 +55,34 @@ class file_info_module extends file_info {
                      'filename' =>null);
     }
 
+    /**
+     * Returns localised visible name.
+     * @return string
+     */
     public function get_visible_name() {
         return $this->cm->name.' ('.get_string('modulename', $this->cm->modname).')';
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return false;
     }
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public function is_directory() {
         return true;
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         $children = array();
         foreach ($this->areas as $area=>$desctiption) {
@@ -71,6 +93,10 @@ class file_info_module extends file_info {
         return $children;
     }
 
+    /**
+     * Returns parent file_info instance
+     * @return file_info or null for root
+     */
     public function get_parent() {
         $pcid = get_parent_contextid($this->context);
         $parent = get_context_instance_by_id($pcid);
diff --git a/lib/file/file_info_stored.php b/lib/file/file_info_stored.php
index e4d82c142d..5c975cc388 100644
--- a/lib/file/file_info_stored.php
+++ b/lib/file/file_info_stored.php
@@ -50,6 +50,12 @@ class file_info_stored extends file_info {
         $this->areaonly       = $areaonly;
     }
 
+    /**
+     * Returns list of standard virtual file/directory identification.
+     * The difference from stored_file parameters is that null values
+     * are allowed in all fields
+     * @return array with keys contextid, filearea, itemid, filepath and filename
+     */
     public function get_params() {
         return array('contextid'=>$this->context->id,
                      'filearea' =>$this->lf->get_filearea(),
@@ -58,6 +64,10 @@ class file_info_stored extends file_info {
                      'filename' =>$this->lf->get_filename());
     }
 
+    /**
+     * Returns localised visible name.
+     * @return string
+     */
     public function get_visible_name() {
         $filename = $this->lf->get_filename();
         $filepath = $this->lf->get_filepath();
@@ -77,6 +87,12 @@ class file_info_stored extends file_info {
         }
     }
 
+    /**
+     * Returns file download url
+     * @param bool $forcedownload
+     * @param bool $htts force https
+     * @return string url
+     */
     public function get_url($forcedownload=false, $https=false) {
         global $CFG;
 
@@ -103,35 +119,66 @@ class file_info_stored extends file_info {
         return file_encode_url($this->urlbase, $path, $forcedownload, $https);
     }
 
+    /**
+     * Can I read content of this file or enter directory?
+     * @return bool
+     */
     public function is_readable() {
         return $this->readaccess;
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return $this->writeaccess;
     }
 
+    /**
+     * Returns file size in bytes, null for directories
+     * @return int bytes or null if not known
+     */
     public function get_filesize() {
         return $this->lf->get_filesize();
     }
 
+    /**
+     * Returns mimetype
+     * @return string mimetype or null if not known
+     */
     public function get_mimetype() {
-        // TODO: add some custom mime icons for courses, categories??
         return $this->lf->get_mimetype();
     }
 
+    /**
+     * Returns time created unix timestamp if known
+     * @return int timestamp or null
+     */
     public function get_timecreated() {
         return $this->lf->get_timecreated();
     }
 
+    /**
+     * Returns time modified unix timestamp if known
+     * @return int timestamp or null
+     */
     public function get_timemodified() {
         return $this->lf->get_timemodified();
     }
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public function is_directory() {
         return $this->lf->is_directory();
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         if (!$this->lf->is_directory()) {
             return array();
@@ -150,6 +197,10 @@ class file_info_stored extends file_info {
         return $result;
     }
 
+    /**
+     * Returns parent file_info instance
+     * @return file_info or null for root
+     */
     public function get_parent() {
         if ($this->lf->get_filepath() === '/' and $this->lf->is_directory()) {
             if ($this->areaonly) {
@@ -175,6 +226,13 @@ class file_info_stored extends file_info {
         return $this->browser->get_file_info($this->context, $this->lf->get_filearea(), $this->lf->get_itemid(), $filepath, '.');
     }
 
+    /**
+     * Create new directory, may throw exception - make sure
+     * params are valid.
+     * @param string $newdirname name of new directory
+     * @param int id of author, default $USER->id
+     * @return file_info new directory
+     */
     public function create_directory($newdirname, $userid=null) {
         if (!$this->is_writable() or !$this->lf->is_directory()) {
             return null;
@@ -196,6 +254,14 @@ class file_info_stored extends file_info {
     }
 
 
+    /**
+     * Create new file from string - make sure
+     * params are valid.
+     * @param string $newfilename name of new file
+     * @param string $content of file
+     * @param int id of author, default $USER->id
+     * @return file_info new file
+     */
     public function create_file_from_string($newfilename, $content, $userid=null) {
         if (!$this->is_writable() or !$this->lf->is_directory()) {
             return null;
@@ -228,6 +294,14 @@ class file_info_stored extends file_info {
         return null;
     }
 
+    /**
+     * Create new file from pathname - make sure
+     * params are valid.
+     * @param string $newfilename name of new file
+     * @param string $pathname location of file
+     * @param int id of author, default $USER->id
+     * @return file_info new file
+     */
     public function create_file_from_pathname($newfilename, $pathname, $userid=null) {
         if (!$this->is_writable() or !$this->lf->is_directory()) {
             return null;
@@ -260,6 +334,14 @@ class file_info_stored extends file_info {
         return null;
     }
 
+    /**
+     * Create new file from stored file - make sure
+     * params are valid.
+     * @param string $newfilename name of new file
+     * @param mixed dile id or stored_file of file
+     * @param int id of author, default $USER->id
+     * @return file_info new file
+     */
     public function create_file_from_storedfile($newfilename, $fid, $userid=null) {
         if (!$this->is_writable() or $this->lf->get_filename() !== '.') {
             return null;
@@ -292,6 +374,10 @@ class file_info_stored extends file_info {
         return null;
     }
 
+    /**
+     * Delete file, make sure file is deletable first.
+     * @return bool success
+     */
     public function delete() {
         if (!$this->is_writable()) {
             return false;
diff --git a/lib/file/file_info_system.php b/lib/file/file_info_system.php
index 3a96830e41..23d0016789 100644
--- a/lib/file/file_info_system.php
+++ b/lib/file/file_info_system.php
@@ -33,6 +33,12 @@ class file_info_system extends file_info {
         parent::__construct($browser, get_context_instance(CONTEXT_SYSTEM));
     }
 
+    /**
+     * Returns list of standard virtual file/directory identification.
+     * The difference from stored_file parameters is that null values
+     * are allowed in all fields
+     * @return array with keys contextid, filearea, itemid, filepath and filename
+     */
     public function get_params() {
         return array('contextid'=>$this->context->id,
                      'filearea' =>null,
@@ -41,18 +47,34 @@ class file_info_system extends file_info {
                      'filename' =>null);
     }
 
+    /**
+     * Returns localised visible name.
+     * @return string
+     */
     public function get_visible_name() {
         return get_string('arearoot', 'repository');
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return false;
     }
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public function is_directory() {
         return true;
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         global $DB, $USER;
 
@@ -87,6 +109,10 @@ class file_info_system extends file_info {
         return $children;
     }
 
+    /**
+     * Returns parent file_info instance
+     * @return file_info or null for root
+     */
     public function get_parent() {
         return null;
     }
diff --git a/lib/file/file_info_user.php b/lib/file/file_info_user.php
index a8856ce9b5..4688598716 100644
--- a/lib/file/file_info_user.php
+++ b/lib/file/file_info_user.php
@@ -46,6 +46,12 @@ class file_info_user extends file_info {
         }
     }
 
+    /**
+     * Returns list of standard virtual file/directory identification.
+     * The difference from stored_file parameters is that null values
+     * are allowed in all fields
+     * @return array with keys contextid, filearea, itemid, filepath and filename
+     */
     public function get_params() {
         return array('contextid'=>$this->context->id,
                      'filearea' =>null,
@@ -54,18 +60,34 @@ class file_info_user extends file_info {
                      'filename' =>null);
     }
 
+    /**
+     * Returns localised visible name.
+     * @return string
+     */
     public function get_visible_name() {
         return fullname($this->user, true);
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return false;
     }
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public function is_directory() {
         return true;
     }
 
+    /**
+     * Returns list of children.
+     * @return array of file_info instances
+     */
     public function get_children() {
         global $USER, $CFG;
 
@@ -84,6 +106,10 @@ class file_info_user extends file_info {
         return $children;
     }
 
+    /**
+     * Returns parent file_info instance
+     * @return file_info or null for root
+     */
     public function get_parent() {
         return $this->browser->get_file_info(get_context_instance(CONTEXT_SYSTEM));
     }
diff --git a/lib/file/file_storage.php b/lib/file/file_storage.php
index d4edcc3ed1..aa03ebd076 100644
--- a/lib/file/file_storage.php
+++ b/lib/file/file_storage.php
@@ -32,7 +32,7 @@ require_once("$CFG->libdir/file/stored_file.php");
  * Only owner of file area may use this class to access own files,
  * for example only code in mod/assignment/* may access assignment
  * attachments. When core needs to access files of modules it has
- * to use file_browser class instead. 
+ * to use file_browser class instead.
  */
 class file_storage {
     private $filedir;
diff --git a/lib/packer/file_packer.php b/lib/packer/file_packer.php
index f04d0714a3..10dd489567 100644
--- a/lib/packer/file_packer.php
+++ b/lib/packer/file_packer.php
@@ -31,7 +31,7 @@
 abstract class file_packer {
 
     /**
-     * archive files and store the result in file storage
+     * Archive files and store the result in file storage
      * @param array $files array with zip paths as keys (archivepath=>ospathname or archivepath=>stored_file) 
      * @param int $contextid
      * @param string $filearea