diff --git a/lib/file/file_storage.php b/lib/file/file_storage.php
index d730edb0dea..ae4243fe590 100644
--- a/lib/file/file_storage.php
+++ b/lib/file/file_storage.php
@@ -1,7 +1,38 @@
-<?php  //$Id$
+<?php
+
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Core file storage class definition.
+ *
+ * @package   moodle-core
+ * @copyright 2008 Petr Skoda (http://skodak.org)
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 require_once("$CFG->libdir/file/stored_file.php");
 
+/**
+ * File storage class used for low level access to stored files.
+ * Only owner of file area may use this class to access own files,
+ * for example only code in mod/assignment/* may access assignment
+ * attachments. When core needs to access files of modules it has
+ * to use file_browser class instead. 
+ */
 class file_storage {
     private $filedir;
 
@@ -25,6 +56,7 @@ class file_storage {
 
     /**
      * Returns location of filedir (file pool)
+     * Do not use, this method is intended for stored_file instances.
      * @return string pathname
      */
     public function get_filedir() {
@@ -32,7 +64,9 @@ class file_storage {
     }
 
     /**
-     * Calculates sha1 hash of unique full path name information
+     * Calculates sha1 hash of unique full path name information,
+     * this hash is a unique file identifier. This improves performance
+     * and overcomes db index size limits.
      * @param int $contextid
      * @param string $filearea
      * @param int $itemid
@@ -77,7 +111,9 @@ class file_storage {
     }
 
     /**
-     * Fetch file using local file id
+     * Fetch file using local file id.
+     * Please do not rely on file ids, it is usually easier to use
+     * pathname hashes instead.
      * @param int $fileid
      * @return mixed stored_file instance if exists, false if not
      */
@@ -107,7 +143,7 @@ class file_storage {
     }
 
     /**
-     * Fetch file
+     * Fetch localy stored file.
      * @param int $contextid
      * @param string $filearea
      * @param int $itemid
@@ -270,7 +306,7 @@ class file_storage {
     }
 
     /**
-     * Recursively creates director
+     * Recursively creates directory
      * @param int $contextid
      * @param string $filearea
      * @param int $itemid