Documentation|libdeng2: Improved apidoc of the File System module

doomsday/libdeng2/include/de/filesys/feed.h

@@ -33,13 +33,15 @@ namespace de
     /**
      * Base class for feeds that generate File and Folder instances.
      *
-     * While File and Folder instances are responsible for the organization of the
-     * data, and provide access to the content bytes, it is up to the Feed instances to
-     * interpret the contents of files and folders and generate the appropriate 
-     * File/Folder instances. When it comes time to repopulate the file system, feeds
-     * are responsible for determining whether a given File or Folder needs to be 
-     * destroyed (pruned). For instance, pruning a NativeFile is necessary if the 
-     * corresponding native file has been deleted from the hard drive since the 
+     * While File and Folder instances are responsible for the organization of
+     * the data, and provide access to the content bytes, it is up to the Feed
+     * instances to interpret the contents of files and folders and generate
+     * the appropriate File/Folder instances.
+     *
+     * When it comes time to repopulate the file system, feeds are responsible
+     * for determining whether a given File or Folder needs to be destroyed
+     * (pruned). For instance, pruning a NativeFile is necessary if the
+     * corresponding native file has been deleted from the hard drive since the
      * latest population was done.
      *
      * @ingroup fs

doomsday/libdeng2/include/de/filesys/file.h

@@ -108,7 +108,9 @@ namespace de
         };
 
         /**
-         * Accesses the properties of a File.
+         * Accesses the properties of a File. Allows using properties of a file
+         * (like its name, path or size) as a Value, for instance in script
+         * expressions.
          *
          * @ingroup fs
          */
@@ -203,11 +205,12 @@ namespace de
         Feed* originFeed() const { return _originFeed; }
 
         /**
-         * Sets the source file of this file. The source is where this file is getting
-         * its data from. File interpreters use this to access their uninterpreted data.
-         * By default all files use themselves as the source, so there is always a
-         * valid source for every file. If another file is being used as the source,
-         * the source is not typically indexed to the file system.
+         * Sets the source file of this file. The source is where this file is
+         * getting its data from. File interpreters use this to access their
+         * uninterpreted data. By default all files use themselves as the
+         * source, so there is always a valid source for every file. If another
+         * file is being used as the source, the source is not typically
+         * indexed to the file system.
          *
          * @param source  Source file. The file takes ownership of @a source.
          */ 
@@ -253,8 +256,9 @@ namespace de
         const Flags& mode() const;
 
         /**
-         * Changes the mode of the file. For example, using <code>WRITE|TRUNCATE</code> as the
-         * mode would empty the contents of the file and open it in writing mode.
+         * Changes the mode of the file. For example, using
+         * <code>WRITE|TRUNCATE</code> as the mode would empty the contents of
+         * the file and open it in writing mode.
          *
          * @param newMode  Mode.
          */

doomsday/libdeng2/include/de/filesys/folder.h

@@ -51,7 +51,9 @@ namespace de
         DENG2_ERROR(NewFileError)
 
         /**
-         * Accesses the properties of a Folder.
+         * Accesses the properties of a Folder. Allows using properties of a
+         * folder (like how many items it contains) as a Value, for instance in
+         * script expressions.
          *
          * @ingroup fs
          */

doomsday/libdeng2/include/de/filesys/fs.h

@@ -28,8 +28,17 @@
 /**
  * @defgroup fs File System
  *
- * The file system (de::FS) governs a tree of files and folders, and provides the means to
- * access all data in libdeng2.
+ * The file system (de::FS) governs a tree of files and folders, and provides
+ * the means to access all data in libdeng2.
+ *
+ * To facilitate efficient O(log n) searches over the entire file system,
+ * de::FS maintains an index of all files and folders by name. There is
+ * additionally a separate index for each file type (e.g., de::ArchiveFile).
+ *
+ * The file system has to be manually refreshed when the underlying data
+ * changes. For instance, when new files are written to a folder on the hard
+ * drive, one must call de::FS::refresh() for the changes to be reflected
+ * in the de::FS index and tree.
  */
 
 namespace de
@@ -44,20 +53,26 @@ namespace de
     /**
      * The file system maintains a tree of files and folders. It provides a way
      * to quickly and efficiently locate files anywhere in the tree. It also
-     * maintains semantic information about the structure and content of the 
+     * maintains semantic information about the structure and content of the
      * file tree, allowing others to know how to treat the files and folders.
      *
-     * In practice, the file system consists of a tree of File and Folder instances.
-     * These instances are generated by the Feed objects attached to the folders.
-     * For instance, a DirectoryFeed will generate the appropriate File and Folder
-     * instances for a directory in the native file system. 
+     * In practice, the file system consists of a tree of File and Folder
+     * instances. These instances are generated by the Feed objects attached to
+     * the folders. For instance, a DirectoryFeed will generate the appropriate
+     * File and Folder instances for a directory in the native file system.
      *
-     * The file system can be repopulated at any time to resynchronize it with the
-     * source data. Repopulation is nondestructive as long as the source data has not
-     * changed. Repopulation is needed for instance when native files get deleted 
-     * in the directory a folder is feeding on. The feeds are responsible for
-     * deciding when instances get out-of-date and need to be deleted (pruning). 
-     * Pruning occurs when a folder that is already populated with files is repopulated.
+     * Wildcard searches are discouraged as implementing them is potentially
+     * inefficient. Instead, suitable indices should be built beforehand if
+     * there is a need to look up lots of files matching a specific criteria
+     * from unknown locations in the tree.
+     *
+     * The file system can be repopulated at any time to resynchronize it with
+     * the source data. Repopulation is nondestructive as long as the source
+     * data has not changed. Repopulation is needed for instance when native
+     * files get deleted in the directory a folder is feeding on. The feeds are
+     * responsible for deciding when instances get out-of-date and need to be
+     * deleted (pruning). Pruning occurs when a folder that is already
+     * populated with files is repopulated.
      *
      * @ingroup fs
      */
@@ -158,23 +173,25 @@ namespace de
         }
 
         /**
-         * Creates an interpreter for the data in a file. 
+         * Creates an interpreter for the data in a file.
          *
-         * @param sourceData  File with the source data. While interpreting, ownership
-         *                    of the file is given to de::FS.
+         * @param sourceData  File with the source data. While interpreting,
+         *                    ownership of the file is given to de::FS.
          *
-         * @return  If the format of the source data was recognized, returns a new File
-         *          that can be used for accessing the data. Ownership of the @a sourceData 
-         *          will be transferred to the new interpreter File instance.
-         *          If the format was not recognized, @a sourceData is returned as is
-         *          and ownership is returned to the caller.
+         * @return If the format of the source data was recognized, returns a
+         * new File (or Folder) that can be used for accessing the data.
+         * Ownership of the @a sourceData will be transferred to the new
+         * interpreter File instance. If the format was not recognized, @a
+         * sourceData is returned as-is and ownership is returned to the
+         * caller.
          */
         File* interpret(File* sourceData);
 
         /**
-         * Provides access to the main index of the file system. This can be used for
-         * efficiently looking up files based on name. @note The file names are
-         * indexed in lower case.
+         * Provides access to the main index of the file system. This can be
+         * used for efficiently looking up files based on name.
+         *
+         * @note The file names are indexed in lower case.
          */
         const Index& nameIndex() const;
 
@@ -183,7 +200,8 @@ namespace de
          *
          * @param typeIdentifier  Type identifier to look for. Use the TYPE_NAME() macro. 
          *
-         * @return  A subset of the main index containing only the entries of the given type.
+         * @return A subset of the main index containing only the entries of
+         * the given type.
          *
          * For example, to look up the index for NativeFile instances:
          * @code