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

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 {
 

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;

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;
 

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;
 

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;

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;

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;

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));

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;
 

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;