From: tjhunt <tjhunt>
Date: Wed, 11 Feb 2009 07:46:53 +0000 (+0000)
Subject: file api: MDL-18111 Improve doc comments a bit.
X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=b81fd01dfe225f137846fc35bb3ed1af8e4c7aaa;p=moodle.git

file api: MDL-18111 Improve doc comments a bit.
---

diff --git a/lib/file/file_browser.php b/lib/file/file_browser.php
index 6cbd6ef387..ff2a0afd1b 100644
--- a/lib/file/file_browser.php
+++ b/lib/file/file_browser.php
@@ -11,7 +11,15 @@ require_once("$CFG->libdir/file/file_info_coursefile.php");
 require_once("$CFG->libdir/file/virtual_root_file.php");
 
 /**
- * Main interface for browsing of file tree (local files, areas, virtual files, etc.).
+ * This class provides the main entry point for other code wishing to get
+ * information about files.
+ *
+ * The whole file storage for a Moodle site can be seen as a huge virtual tree.
+ * The spine of the tree is the tree of contexts (system, course-categories,
+ * courses, modules, also users). Then, within each context, there may be any number of
+ * file areas, and a file area contains folders and files. The various file_info
+ * subclasses return info about the things in this tree. They should be obtained
+ * from an instance of this class.
  */
 class file_browser {
 
diff --git a/lib/file/file_info.php b/lib/file/file_info.php
index eaa3fa95b6..14ceb83080 100644
--- a/lib/file/file_info.php
+++ b/lib/file/file_info.php
@@ -1,5 +1,8 @@
 <?php  //$Id$
 
+/**
+ * Base class for things in the tree navigated by @see{file_browser}.
+ */
 abstract class file_info {
     protected $context;
     protected $browser;
diff --git a/lib/file/file_info_course.php b/lib/file/file_info_course.php
index f723b805bd..939555c0c9 100644
--- a/lib/file/file_info_course.php
+++ b/lib/file/file_info_course.php
@@ -1,5 +1,8 @@
 <?php  //$Id$
 
+/**
+ * Represents a course context in the tree navigated by @see{file_browser}.
+ */
 class file_info_course extends file_info {
     protected $course;
 
diff --git a/lib/file/file_info_coursecat.php b/lib/file/file_info_coursecat.php
index a4797735b2..409d8f9d9f 100644
--- a/lib/file/file_info_coursecat.php
+++ b/lib/file/file_info_coursecat.php
@@ -1,5 +1,8 @@
 <?php  //$Id$
 
+/**
+ * Represents a course category context in the tree navigated by @see{file_browser}.
+ */
 class file_info_coursecat extends file_info {
     protected $category;
 
diff --git a/lib/file/file_info_coursefile.php b/lib/file/file_info_coursefile.php
index 1f201e8412..9e07380f1e 100644
--- a/lib/file/file_info_coursefile.php
+++ b/lib/file/file_info_coursefile.php
@@ -1,5 +1,8 @@
 <?php  //$Id$
 
+/**
+ * Subclass of file_info_stored for files in the course files area.
+ */
 class file_info_coursefile extends file_info_stored {
     public function __construct($browser, $context, $storedfile) {
         global $CFG;
diff --git a/lib/file/file_info_module.php b/lib/file/file_info_module.php
index 7b1951eaf1..a027fd3f94 100644
--- a/lib/file/file_info_module.php
+++ b/lib/file/file_info_module.php
@@ -1,5 +1,8 @@
 <?php  //$Id$
 
+/**
+ * Represents a module context in the tree navigated by @see{file_browser}.
+ */
 class file_info_module extends file_info {
     protected $course;
     protected $cm;
diff --git a/lib/file/file_info_stored.php b/lib/file/file_info_stored.php
index f5df2f108b..2bf82bf03c 100644
--- a/lib/file/file_info_stored.php
+++ b/lib/file/file_info_stored.php
@@ -1,5 +1,9 @@
 <?php  //$Id$
 
+/**
+ * Represents an actual file or folder - a row in the file table -
+ * in the tree navigated by @see{file_browser}.
+ */
 class file_info_stored extends file_info {
     protected $lf;
     protected $urlbase;
diff --git a/lib/file/file_info_system.php b/lib/file/file_info_system.php
index bd3cd66188..f2bcb175f1 100644
--- a/lib/file/file_info_system.php
+++ b/lib/file/file_info_system.php
@@ -1,5 +1,8 @@
 <?php  //$Id$
 
+/**
+ * Represents the system context in the tree navigated by @see{file_browser}.
+ */
 class file_info_system extends file_info {
     public function __construct($browser) {
         parent::__construct($browser, get_context_instance(CONTEXT_SYSTEM));
diff --git a/lib/file/file_info_user.php b/lib/file/file_info_user.php
index f26e9d3e10..bf6e62d7e2 100644
--- a/lib/file/file_info_user.php
+++ b/lib/file/file_info_user.php
@@ -1,5 +1,8 @@
 <?php  //$Id$
 
+/**
+ * Represents a user context in the tree navigated by @see{file_browser}.
+ */
 class file_info_user extends file_info {
     protected $user;
 
diff --git a/lib/file/virtual_root_file.php b/lib/file/virtual_root_file.php
index 526956180d..e97fdd15b4 100644
--- a/lib/file/virtual_root_file.php
+++ b/lib/file/virtual_root_file.php
@@ -1,7 +1,8 @@
 <?php  //$Id$
 
 /**
- * Root directory in empty file area
+ * Represents the root directory of an empty file area in the tree navigated by
+ * @see{file_browser}.
  */
 class virtual_root_file {
     protected $contextid;