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

MDL-18111 improving file api comments and docs, fixing license header
---

diff --git a/lib/file/file_info.php b/lib/file/file_info.php
index aced4783c6..c4ccd63449 100644
--- a/lib/file/file_info.php
+++ b/lib/file/file_info.php
@@ -39,16 +39,42 @@ abstract class file_info {
         $this->context = $context;
     }
 
+    /**
+     * 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 abstract function get_params();
 
+    /**
+     * Returns localised visible name.
+     * @return string
+     */
     public abstract function get_visible_name();
 
+    /**
+     * Is directory?
+     * @return bool
+     */
     public abstract function is_directory();
 
+    /**
+     * Does this node have children?
+     * @return bool
+     */
     public abstract function get_children();
 
+    /**
+     * Returns parent file_info instance
+     * @return file_info or null for root
+     */
     public abstract function get_parent();
 
+    /**
+     * Returns array of url encoded params.
+     * @return array with numeric keys
+     */
     public function get_params_rawencoded() {
         $params = $this->get_params();
         $encoded = array();
@@ -61,51 +87,115 @@ abstract class file_info {
         return $encoded;
     }
 
+    /**
+     * Returns download url for
+     * @param bool $forcedownload
+     * @param bool $htts force https
+     * @return string url
+     */
     public function get_url($forcedownload=false, $https=false) {
         return null;
     }
 
+    /**
+     * Can I read content of this file or enter directory?
+     * @return bool
+     */
     public function is_readable() {
         return true;
     }
 
+    /**
+     * Can I add new files or directories?
+     * @return bool
+     */
     public function is_writable() {
         return true;
     }
 
+    /**
+     * Returns file size in bytes, null for directories
+     * @return int bytes or null if not known
+     */
     public function get_filesize() {
         return null;
     }
 
+    /**
+     * Returns mimetype
+     * @return string mimetype or null if not known
+     */
     public function get_mimetype() {
-        // TODO: add some custom mime icons for courses, categories??
         return null;
     }
 
+    /**
+     * Returns time created unix timestamp if known
+     * @return int timestamp or null
+     */
     public function get_timecreated() {
         return null;
     }
 
+    /**
+     * Returns time modified unix timestamp if known
+     * @return int timestamp or null
+     */
     public function get_timemodified() {
         return null;
     }
 
+    /**
+     * 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) {
         return null;
     }
 
+    /**
+     * 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) {
         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) {
         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) {
         return null;
     }
 
+    /**
+     * Delete file, make sure file is deletable first.
+     * @return bool success
+     */
     public function delete() {
         return false;
     }