Issue 116 - Document the libadblockplus API

include/AdblockPlus/FileSystem.h

Index: include/AdblockPlus/FileSystem.h
===================================================================
--- a/include/AdblockPlus/FileSystem.h
+++ b/include/AdblockPlus/FileSystem.h
@@ -26,9 +26,15 @@
 
 namespace AdblockPlus
 {
+  /**
+   * File system interface.
+   */
   class FileSystem
   {
   public:
+    /**
+     * Result of a stat operation, i.e.\ information about a file.
+     */
     struct StatResult
     {
       StatResult()
@@ -39,24 +45,77 @@
         lastModified = 0;
       }
 
+      /**
+       * File exists.
+       */
       bool exists;
+
+      /**
+       * File is a directory.
+       */
       bool isDirectory;
+
+      /**
+       * File is a regular file.
+       */
       bool isFile;
+
+      /**
+       * POSIX time of the last modification.
+       */
       int64_t lastModified;
     };
 
     virtual ~FileSystem() {}
+
+    /**
+     * Reads from a file.
+     * @param path File path.
+     * @return Input stream with the file's contents.
+     */
     virtual std::tr1::shared_ptr<std::istream>
       Read(const std::string& path) const = 0;
+
+    /**
+     * Writes to a file.
+     * @param path File path.
+     * @param data Input stream with the data to write.
+     */
     virtual void Write(const std::string& path,
                        std::tr1::shared_ptr<std::istream> data) = 0;
+
+    /**
+     * Moves a file (i.e.\ renames it).
+     * @param fromPath Current path to the file.
+     * @param toPath New path to the file.
+     */
     virtual void Move(const std::string& fromPath,
                       const std::string& toPath) = 0;
+
+    /**
+     * Removes a file.
+     * @param path File path.
+     */
     virtual void Remove(const std::string& path) = 0;
+
+    /**
+     * Retrieves information about a file.
+     * @param path File path.
+     * @return File information.
+     */
     virtual StatResult Stat(const std::string& path) const = 0;
+
+    /**
+     * Returns the absolute path to a file.
+     * @param path File path (can be relative or absolute).
+     * @return Absolute file path.
+     */
     virtual std::string Resolve(const std::string& path) const = 0;
   };
 
+  /**
+   * Shared smart pointer to a `FileSystem` instance.
+   */
   typedef std::tr1::shared_ptr<FileSystem> FileSystemPtr;
 }