[Scummvm-cvs-logs] SF.net SVN: scummvm:[55403] scummvm/trunk/common/macresman.h

[mthreepwood at users.sourceforge.net]

Revision: 55403
          http://scummvm.svn.sourceforge.net/scummvm/?rev=55403&view=rev
Author:   mthreepwood
Date:     2011-01-22 02:31:30 +0000 (Sat, 22 Jan 2011)

Log Message:
-----------
COMMON: Update documentation of the MacResManager

Modified Paths:
--------------
    scummvm/trunk/common/macresman.h

Modified: scummvm/trunk/common/macresman.h
===================================================================
--- scummvm/trunk/common/macresman.h	2011-01-22 01:07:14 UTC (rev 55402)
+++ scummvm/trunk/common/macresman.h	2011-01-22 02:31:30 UTC (rev 55403)
@@ -23,6 +23,15 @@
  *
  */
 
+/**
+ * @file
+ * Macintosh resource fork manager used in engines:
+ * - groovie
+ * - mohawk
+ * - sci
+ * - scumm
+ */
+
 #include "common/array.h"
 #include "common/file.h"
 
@@ -37,8 +46,8 @@
 typedef Array<uint32> MacResTagArray;
 
 /**
- * Class for reading Mac Binary files.
- * Is able to read dumped resource forks too.
+ * Class for handling Mac data and resource forks.
+ * It can read from raw, MacBinary, and AppleDouble formats.
  */
 class MacResManager {
 
@@ -46,17 +55,48 @@
 	MacResManager();
 	~MacResManager();
 
+	/**
+	 * Open a Mac data/resource fork pair.
+	 * @param filename The base file name of the file
+	 * @note This will check for the raw resource fork, MacBinary, and AppleDouble formats.
+	 * @return True on success
+	 */
 	bool open(String filename);
+
+	/**
+	 * Open a Mac data/resource fork pair.
+	 * @param path The path that holds the forks
+	 * @param filename The base file name of the file
+	 * @note This will check for the raw resource fork, MacBinary, and AppleDouble formats.
+	 * @return True on success
+	 */
 	bool open(FSNode path, String filename);
+
+	/**
+	 * Close the Mac data/resource fork pair.
+	 */
 	void close();
 
+	/**
+	 * Query whether or not we have a data fork present.
+	 * @return True if the data fork is present
+	 */
 	bool hasDataFork() const;
+
+	/**
+	 * Query whether or not we have a data fork present.
+	 * @return True if the resource fork is present
+	 */
 	bool hasResFork() const;
 
+	/**
+	 * Check if the given stream is in the MacBinary format.
+	 * @param stream The stream we're checking
+	 */
 	static bool isMacBinary(SeekableReadStream &stream);
 
 	/**
-	 * Read resource from the Mac Binary file
+	 * Read resource from the MacBinary file
 	 * @param typeID FourCC of the type
 	 * @param resID Resource ID to fetch
 	 * @return Pointer to a SeekableReadStream with loaded resource
@@ -64,26 +104,52 @@
 	SeekableReadStream *getResource(uint32 typeID, uint16 resID);
 
 	/**
-	 * Read resource from the Mac Binary file
+	 * Read resource from the MacBinary file
 	 * @note This will take the first resource that matches this name, regardless of type
-	 * @param filename filename of the resource
+	 * @param filename file name of the resource
 	 * @return Pointer to a SeekableReadStream with loaded resource
 	 */
 	SeekableReadStream *getResource(const String &filename);
 
 	/**
-	 * Read resource from the Mac Binary file
+	 * Read resource from the MacBinary file
 	 * @param typeID FourCC of the type
-	 * @param filename filename of the resource
+	 * @param filename file name of the resource
 	 * @return Pointer to a SeekableReadStream with loaded resource
 	 */
 	SeekableReadStream *getResource(uint32 typeID, const String &filename);
 
+	/**
+	 * Retrieve the data fork
+	 * @return The stream if present, 0 otherwise
+	 */
 	SeekableReadStream *getDataFork();
+
+	/**
+	 * Get the name of a given resource
+	 * @param typeID FourCC of the type
+	 * @param resID Resource ID to fetch
+	 * @return The name of a given resource and an empty string if not present
+	 */
 	String getResName(uint32 typeID, uint16 resID) const;
+
+	/**
+	 * Get the size of the resource fork
+	 * @return The size of the resource fork
+	 */
 	uint32 getResForkSize() const;
+
+	/**
+	 * Calculate the MD5 checksum of the resource fork
+	 * @param length The maximum length to compute for
+	 * @return The MD5 checksum of the resource fork
+	 */
 	String computeResForkMD5AsString(uint32 length = 0) const;
 
+	/**
+	 * Get the base file name of the data/resource fork pair
+	 * @return The base file name of the data/resource fork pair
+	 */
 	String getBaseFileName() const { return _baseFileName; }
 
 	/**


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.