Documentation|libdeng2: More PackageFolder documentation, fixes

skyjake · Dec 1, 2012 · 7a85e24 · 7a85e24
1 parent 53b0b67
commit 7a85e24
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 6 deletions.
diff --git a/doomsday/libdeng2/include/de/data/record.h b/doomsday/libdeng2/include/de/data/record.h
@@ -38,7 +38,7 @@ namespace de
      * A set of variables. A record may have any number of subrecords. Note
      * that the members of a record do not have an order.
      *
-     * A @m subrecord is a record that is owned by one of the members of the
+     * A @em subrecord is a record that is owned by one of the members of the
      * main record. The ownership chain is as follows: Record -> Variable ->
      * RecordValue -> Record.
      *

diff --git a/doomsday/libdeng2/include/de/filesys/packagefolder.h b/doomsday/libdeng2/include/de/filesys/packagefolder.h
@@ -26,10 +26,20 @@
 namespace de {
 
 /**
- * Specialized Folder that hosts a data package archive. When a ZIP-format file
- * is interpreted, it will be represented in the file system by a
- * PackageFolder, while the contents of the ZIP file are represented by
- * ArchiveEntryFile instances.
+ * Specialized Folder that hosts a data package archive.
+ *
+ * A @em package is a collection is files packaged into a single unit (possibly
+ * using an Archive). Examples of packages are add-on packages (in various
+ * formats, e.g., PK3/ZIP archive or the Snowberry add-on bundle), savegames,
+ * custom maps, and demos.
+ *
+ * When a ZIP-format file is interpreted, it will be represented in the file
+ * system by a PackageFolder, while the contents of the ZIP file are
+ * represented by ArchiveEntryFile instances.
+ *
+ * @todo In addition to providing easy access to the Archive of the package,
+ * PackageFolder should also make it convenient to access the metadata of the
+ * package (read from the contained Info file).
  *
  * @see ArchiveFeed
  */
@@ -41,7 +51,9 @@ class PackageFolder : public Folder
      * and a feed is attached for populating the folder with entries from the
      * archive.
      *
-     * @param sourceArchiveFile  Source file that contains an archive.
+     * @param sourceArchiveFile  Source file that contains an archive. The
+     *                           ArchiveFeed that will be attached to the
+     *                           PackageFolder uses this file as its source.
      * @param name               Name for the folder.
      */
     PackageFolder(File &sourceArchiveFile, String const &name = "");

diff --git a/doomsday/libdeng2/src/filesys/archivefeed.cpp b/doomsday/libdeng2/src/filesys/archivefeed.cpp
@@ -49,6 +49,8 @@ struct ArchiveFeed::Instance
 
     Instance(ArchiveFeed *feed, File &f) : self(*feed), file(f), arch(0), parentFeed(0)
     {
+        /// @todo Observe the file for deletion.
+
         // If the file happens to be a byte array file, we can use it
         // directly to store the Archive.
         IByteArray *bytes = dynamic_cast<IByteArray *>(&f);