From b81fd01dfe225f137846fc35bb3ed1af8e4c7aaa Mon Sep 17 00:00:00 2001
From: tjhunt <tjhunt>
Date: Wed, 11 Feb 2009 07:46:53 +0000
Subject: [PATCH] file api: MDL-18111 Improve doc comments a bit.

---
 lib/file/file_browser.php         | 10 +++++++++-
 lib/file/file_info.php            |  3 +++
 lib/file/file_info_course.php     |  3 +++
 lib/file/file_info_coursecat.php  |  3 +++
 lib/file/file_info_coursefile.php |  3 +++
 lib/file/file_info_module.php     |  3 +++
 lib/file/file_info_stored.php     |  4 ++++
 lib/file/file_info_system.php     |  3 +++
 lib/file/file_info_user.php       |  3 +++
 lib/file/virtual_root_file.php    |  3 ++-
 10 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/lib/file/file_browser.php b/lib/file/file_browser.php
index 6cbd6ef387e..ff2a0afd1b5 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 eaa3fa95b68..14ceb830808 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 f723b805bd9..939555c0c97 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 a4797735b2b..409d8f9d9ff 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 1f201e84120..9e07380f1eb 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 7b1951eaf1d..a027fd3f942 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 f5df2f108be..2bf82bf03c5 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 bd3cd661880..f2bcb175f11 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 f26e9d3e10b..bf6e62d7e20 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 526956180d1..e97fdd15b4b 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;