VIDEO: Add some documentation to Codec and its derivatives

12 files changed, 100 insertions, 4 deletions

diff --git a/video/codecs/cdtoons.h b/video/codecs/cdtoons.h
index 8f6d3acb6e..e6b7aab5f8 100644
--- a/video/codecs/cdtoons.h
+++ b/video/codecs/cdtoons.h
@@ -38,6 +38,12 @@ struct CDToonsBlock {
 	byte *data;
 };
 
+/**
+ * Broderbund CDToons decoder.
+ *
+ * Used in video:
+ *  - QuickTimeDecoder
+ */
 class CDToonsDecoder : public Codec {
 public:
 	CDToonsDecoder(uint16 width, uint16 height);
diff --git a/video/codecs/cinepak.h b/video/codecs/cinepak.h
index 7abda6f400..f4adfd50fe 100644
--- a/video/codecs/cinepak.h
+++ b/video/codecs/cinepak.h
@@ -59,6 +59,13 @@ struct CinepakFrame {
 	Graphics::Surface *surface;
 };
 
+/**
+ * Cinepak decoder.
+ *
+ * Used in video:
+ *  - AVIDecoder
+ *  - QuickTimeDecoder
+ */
 class CinepakDecoder : public Codec {
 public:
 	CinepakDecoder(int bitsPerPixel = 24);
diff --git a/video/codecs/codec.h b/video/codecs/codec.h
index 8e4691ca3c..c1194e461b 100644
--- a/video/codecs/codec.h
+++ b/video/codecs/codec.h
@@ -32,16 +32,48 @@ class SeekableReadStream;
 
 namespace Video {
 
+/**
+ * An abstract representation of a video codec used for decoding
+ * video frames.
+ *
+ * Used in video:
+ *  - AVIDecoder
+ *  - QuickTimeDecoder
+ *  - VMDDecoder
+ */
 class Codec {
 public:
 	Codec() {}
 	virtual ~Codec() {}
 
+	/**
+	 * Decode the frame for the given data and return a pointer to a surface
+	 * containing the decoded frame.
+	 *
+	 * @return a pointer to the decoded frame
+	 * @note stream is not deleted 
+	 */
 	virtual const Graphics::Surface *decodeImage(Common::SeekableReadStream *stream) = 0;
+
+	/**
+	 * Get the format that the surface returned from decodeImage() will
+	 * be in.
+	 */
 	virtual Graphics::PixelFormat getPixelFormat() const = 0;
 
+	/**
+	 * Can this codec's frames contain a palette?
+	 */
 	virtual bool containsPalette() const { return false; }
+
+	/**
+	 * Get the palette last decoded from decodeImage
+	 */
 	virtual const byte *getPalette() { return 0; }
+
+	/**
+	 * Does the codec have a dirty palette?
+	 */
 	virtual bool hasDirtyPalette() const { return false; }
 };
 
diff --git a/video/codecs/indeo3.h b/video/codecs/indeo3.h
index a07d779dec..880901df13 100644
--- a/video/codecs/indeo3.h
+++ b/video/codecs/indeo3.h
@@ -36,6 +36,13 @@
 
 namespace Video {
 
+/**
+ * Intel Indeo 3 decoder.
+ *
+ * Used in video:
+ *  - AVIDecoder
+ *  - VMDDecoder
+ */
 class Indeo3Decoder : public Codec {
 public:
 	Indeo3Decoder(uint16 width, uint16 height);
diff --git a/video/codecs/mjpeg.h b/video/codecs/mjpeg.h
index 0c3b668a74..d71454799c 100644
--- a/video/codecs/mjpeg.h
+++ b/video/codecs/mjpeg.h
@@ -36,10 +36,12 @@ struct Surface;
 
 namespace Video {
 
-// Motion JPEG Decoder
-// Basically a wrapper around JPEG which converts to RGB and also functions
-// as a Codec.
-
+/**
+ * Motion JPEG decoder.
+ *
+ * Used in video:
+ *  - QuickTimeDecoder
+ */
 class JPEGDecoder : public Codec {
 public:
 	JPEGDecoder();
diff --git a/video/codecs/msrle.h b/video/codecs/msrle.h
index 2aea66d113..64ebaaee51 100644
--- a/video/codecs/msrle.h
+++ b/video/codecs/msrle.h
@@ -27,6 +27,12 @@
 
 namespace Video {
 
+/**
+ * Microsoft Run-Length Encoding decoder.
+ *
+ * Used in video:
+ *  - AVIDecoder
+ */
 class MSRLEDecoder : public Codec {
 public:
 	MSRLEDecoder(uint16 width, uint16 height, byte bitsPerPixel);
diff --git a/video/codecs/msvideo1.h b/video/codecs/msvideo1.h
index 767eece580..047d542743 100644
--- a/video/codecs/msvideo1.h
+++ b/video/codecs/msvideo1.h
@@ -27,6 +27,12 @@
 
 namespace Video {
 
+/**
+ * Microsoft Video 1 decoder.
+ *
+ * Used in video:
+ *  - AVIDecoder
+ */
 class MSVideo1Decoder : public Codec {
 public:
 	MSVideo1Decoder(uint16 width, uint16 height, byte bitsPerPixel);
diff --git a/video/codecs/qtrle.h b/video/codecs/qtrle.h
index d9db58ab23..a1dd9c9188 100644
--- a/video/codecs/qtrle.h
+++ b/video/codecs/qtrle.h
@@ -28,6 +28,12 @@
 
 namespace Video {
 
+/**
+ * QuickTime Run-Length Encoding decoder.
+ *
+ * Used in video:
+ *  - QuickTimeDecoder
+ */
 class QTRLEDecoder : public Codec {
 public:
 	QTRLEDecoder(uint16 width, uint16 height, byte bitsPerPixel);
diff --git a/video/codecs/rpza.h b/video/codecs/rpza.h
index f082d25549..67e0699692 100644
--- a/video/codecs/rpza.h
+++ b/video/codecs/rpza.h
@@ -28,6 +28,12 @@
 
 namespace Video {
 
+/**
+ * Apple RPZA decoder.
+ *
+ * Used in video:
+ *  - QuickTimeDecoder
+ */
 class RPZADecoder : public Codec {
 public:
 	RPZADecoder(uint16 width, uint16 height);
diff --git a/video/codecs/smc.h b/video/codecs/smc.h
index f2caca977a..4b9f57410a 100644
--- a/video/codecs/smc.h
+++ b/video/codecs/smc.h
@@ -34,6 +34,12 @@ enum {
 	COLORS_PER_TABLE = 256
 };
 
+/**
+ * Apple SMC decoder.
+ *
+ * Used in video:
+ *  - QuickTimeDecoder
+ */
 class SMCDecoder : public Codec {
 public:
 	SMCDecoder(uint16 width, uint16 height);
diff --git a/video/codecs/svq1.h b/video/codecs/svq1.h
index e5066abfd4..6667fea344 100644
--- a/video/codecs/svq1.h
+++ b/video/codecs/svq1.h
@@ -33,6 +33,12 @@ struct Point;
 
 namespace Video {
 
+/**
+ * Sorenson Vector Quantizer 1 decoder.
+ *
+ * Used in video:
+ *  - QuickTimeDecoder
+ */
 class SVQ1Decoder : public Codec {
 public:
 	SVQ1Decoder(uint16 width, uint16 height);
diff --git a/video/codecs/truemotion1.h b/video/codecs/truemotion1.h
index 628cfa4584..b2a35cf873 100644
--- a/video/codecs/truemotion1.h
+++ b/video/codecs/truemotion1.h
@@ -32,6 +32,12 @@
 
 namespace Video {
 
+/**
+ * Duck TrueMotion 1 decoder.
+ *
+ * Used in video:
+ *  - AVIDecoder
+ */
 class TrueMotion1Decoder : public Codec {
 public:
 	TrueMotion1Decoder(uint16 width, uint16 height);