Documentation: Updated apidoc for ZipFile

doomsday/engine/portable/include/zipfile.h

@@ -1,60 +1,108 @@
-/**\file zipfile.h
- *\section License
- * License: GPL
- * Online License Link: http://www.gnu.org/licenses/gpl.html
- *
- *\author Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
- *\author Copyright © 2005-2012 Daniel Swanson <danij@dengine.net>
- *
- * This program 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 2 of the License, or
- * (at your option) any later version.
- *
- * This program 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 this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin St, Fifth Floor,
- * Boston, MA  02110-1301  USA
+/**
+ * @file zipfile.h
+ * Specialization of AbstractFile for working with Zip archives.
+ *
+ * @note Presently only the zlib method (Deflate) of compression is supported.
+ *
+ * @ingroup fs
+ *
+ * @see abstractfile.h, AbstractFile
+ *
+ * @authors Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
+ * @authors Copyright &copy; 2005-2012 Daniel Swanson <danij@dengine.net>
+ *
+ * @par License
+ * GPL: http://www.gnu.org/licenses/gpl.html
+ *
+ * <small>This program 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 2 of the License, or (at your
+ * option) any later version. This program 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 this program; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA</small>
  */
 
 #ifndef LIBDENG_FILESYS_ZIPFILE_H
 #define LIBDENG_FILESYS_ZIPFILE_H
 
-#include "lumpinfo.h"
 #include "abstractfile.h"
+#include "lumpinfo.h"
+#include "lumpdirectory.h"
 
-struct lumpdirectory_s;
 struct pathdirectorynode_s;
+struct zipfile_s;
 
 /**
- * ZipFile. Runtime representation of Zip files.
- *
- * Uses zlib for decompression of "Deflated" files.
- *
- * @ingroup FS
+ * ZipFile instance. Constructed with ZipFile_New().
  */
-struct zipfile_s; // The zipfile instance (opaque)
 typedef struct zipfile_s ZipFile;
 
+/**
+ * Constructs a new zipfile. The zipfile has to be destroyed with ZipFile_Delete()
+ * after it is not needed any more.
+ *
+ * @param file  Virtual file handle to the underlying file resource.
+ * @param path  Virtual file system path to associate with the resultant zipfile.
+ * @param info  File info descriptor for the resultant zipfile. A copy is made.
+ */
 ZipFile* ZipFile_New(DFile* file, const char* path, const LumpInfo* info);
+
+/**
+ * Destroys the zipfile.
+ */
 void ZipFile_Delete(ZipFile* zip);
 
-int ZipFile_PublishLumpsToDirectory(ZipFile* zip, struct lumpdirectory_s* directory);
+/**
+ * Publish lumps to the end of the specified @a directory and prune any duplicates
+ * (see LumpDirectory_PruneDuplicateRecords()).
+ *
+ * @param zip  ZipFile instance.
+ * @param directory  Directory to publish to.
+ * @return  Number of lumps published to the directory (not necessarily the same as
+ *          ZipFile_LumpCount()).
+ */
+int ZipFile_PublishLumpsToDirectory(ZipFile* zip, LumpDirectory* directory);
 
+/**
+ * Lookup a directory node for a lump contained by this zipfile.
+ *
+ * @param zip  ZipFile instance.
+ * @param lumpIdx  Logical index for the lump within the zipfile's internal directory.
+ * @return  Found directory node else @c NULL if @a lumpIdx is not valid.
+ */
 struct pathdirectorynode_s* ZipFile_LumpDirectoryNode(ZipFile* zip, int lumpIdx);
 
-ddstring_t* ZipFile_ComposeLumpPath(ZipFile* zip, int lumpIdx, char delimiter);
-
+/**
+ * Lookup a lump info descriptor for a lump contained by this zipfile.
+ *
+ * @param zip  ZipFile instance.
+ * @param lumpIdx  Logical index for the lump within the zipfile's internal directory.
+ * @return  Found lump info else @c NULL if @a lumpIdx is not valid.
+ */
 const LumpInfo* ZipFile_LumpInfo(ZipFile* zip, int lumpIdx);
 
+/**
+ * Compose the full virtual file system path to a lump contained by this zipfile.
+ *
+ * @note Always runs a valid string object. In the case of an invalid @a lumpIdx
+ *       a zero-length string is returned.
+ *
+ * @param zip  ZipFile instance.
+ * @param lumpIdx  Logical index for the lump.
+ * @param delimiter  Delimit directory separators using this character (default: '/').
+ * @return  String containing the full path. Has to be destroyed with Str_Delete()
+ *          once it is no longer needed.
+ */
+ddstring_t* ZipFile_ComposeLumpPath(ZipFile* zip, int lumpIdx, char delimiter);
+
 /**
  * Read the data associated with the specified lump index into @a buffer.
  *
+ * @param zip  ZipFile instance.
  * @param lumpIdx  Lump index associated with the data being read.
  * @param buffer  Buffer to read into. Must be at least W_LumpLength() bytes.
  * @param tryCache  @c true = try the lump cache first.
@@ -66,6 +114,7 @@ size_t ZipFile_ReadLump(ZipFile* zip, int lumpIdx, uint8_t* buffer);
 /**
  * Read a subsection of the data associated with the specified lump index into @a buffer.
  *
+ * @param zip  ZipFile instance.
  * @param lumpIdx  Lump index associated with the data being read.
  * @param buffer  Buffer to read into. Must be at least W_LumpLength() bytes.
  * @param startOffset  Offset from the beginning of the lump to start reading.
@@ -81,6 +130,7 @@ size_t ZipFile_ReadLumpSection(ZipFile* zip, int lumpIdx, uint8_t* buffer,
 /**
  * Read the data associated with the specified lump index into the cache.
  *
+ * @param zip  ZipFile instance.
  * @param lumpIdx  Lump index associated with the data being read.
  * @param tag  Zone purge level/cache tag to use.
  * @return  Ptr to the cached copy of the associated data.
@@ -90,6 +140,7 @@ const uint8_t* ZipFile_CacheLump(ZipFile* zip, int lumpIdx, int tag);
 /**
  * Change the Zone purge level/cache tag associated with a cached data lump.
  *
+ * @param zip  ZipFile instance.
  * @param lumpIdx  Lump index associated with the cached data being changed.
  * @param tag  Zone purge level/cache tag to use.
  */
@@ -109,10 +160,11 @@ int ZipFile_LumpCount(ZipFile* zip);
  */
 
 /**
- * Does the specified file appear to be in Zip format.
+ * Does the specified file appear to be in a format recognised by ZipFile?
+ *
  * @param file  Stream file handle/wrapper to the file being interpreted.
  * @return  @c true iff this is a file that can be represented using ZipFile.
  */
 boolean ZipFile_Recognise(DFile* file);
 
-#endif
+#endif // LIBDENG_FILESYS_ZIPFILE_H