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

diff --git a/lib/file/file_browser.php b/lib/file/file_browser.php
index 6cbd6ef387e1c4d73a81d9e568c23ca669ad45ab..ff2a0afd1b534ffb3dc69e119e53bd9d4cce4122 100644 (file)
--- 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 eaa3fa95b6883c4a81d34ca779f8268007f3af42..14ceb83080849a83632ab6fad879497cad1d7415 100644 (file)
--- 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 f723b805bd9e21cc3feb795bd38d4ebed7a361ce..939555c0c97106a358587f9e0275dc4a45da74e2 100644 (file)
--- 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 a4797735b2b8ffeb0b3fc6434c19e40f11c2a8ec..409d8f9d9ff35e79ff72b7121fd603085fbfd5a5 100644 (file)
--- 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 1f201e84120496943d4db03d6e6cefe75d607597..9e07380f1ebabe37a56fce95d461ed7f081c84d2 100644 (file)
--- 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 7b1951eaf1d135371ec689bee080b119c739cc6c..a027fd3f9428e81249b193c60714cb54768222e7 100644 (file)
--- 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 f5df2f108be0098bbf3133b1e5c5b9760ea42dee..2bf82bf03c510dcacf9e8a205172f245d79c4087 100644 (file)
--- 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 bd3cd6618802504ef700640fb9529943136f9719..f2bcb175f11e71042b592f127cceebe53819228c 100644 (file)
--- 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 f26e9d3e10bf289d0bd72759efe6a9c17e62566f..bf6e62d7e20e1026b4336478cd2cd8c503cc623f 100644 (file)
--- 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 526956180d1cd68fb794c87c063a6d854abe565c..e97fdd15b4b681595b592d7acb9e40062bfd3d12 100644 (file)
--- 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;