From d71db75062556dc2aea073a33e0e102894b6dfa5 Mon Sep 17 00:00:00 2001
From: Mikko Rasa <tdb@tdb.fi>
Date: Sun, 24 Jun 2018 17:47:45 +0300
Subject: [PATCH] Improve documentation of SoundDecoder

---
 source/mp3decoder.h   |  4 ++++
 source/oggdecoder.h   |  4 ++++
 source/sounddecoder.h | 16 ++++++++++++++--
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/source/mp3decoder.h b/source/mp3decoder.h
index 201d68f..01fba63 100644
--- a/source/mp3decoder.h
+++ b/source/mp3decoder.h
@@ -18,6 +18,10 @@ private:
 };
 
 
+/**
+Decoder for MPEG-2 audio files, a.k.a. MP2 and MP3 files.  Normally you should
+use one of the SoundDecoder::open_* functions to create a decoder.
+*/
 class Mp3Decoder: public SoundDecoder
 {
 private:
diff --git a/source/oggdecoder.h b/source/oggdecoder.h
index 3bf33b8..e194736 100644
--- a/source/oggdecoder.h
+++ b/source/oggdecoder.h
@@ -18,6 +18,10 @@ private:
 };
 
 
+/**
+Decoder for Ogg Vorbis files.  Normally you should use one of the
+SoundDecoder::open_* functions to create a decoder.
+*/
 class OggDecoder: public SoundDecoder
 {
 private:
diff --git a/source/sounddecoder.h b/source/sounddecoder.h
index 37fddac..20b9d0f 100644
--- a/source/sounddecoder.h
+++ b/source/sounddecoder.h
@@ -17,8 +17,7 @@ public:
 
 
 /**
-This class facilitates loading sound files.  Currently only Ogg Vorbis is
-supported.
+Base class for sound decoders.
 */
 class SoundDecoder
 {
@@ -34,16 +33,29 @@ protected:
 public:
 	virtual ~SoundDecoder();
 
+	/** Opens a file and creates a decoder of an appropriate type for it. */
 	static SoundDecoder *open_file(const std::string &);
+
+	/** Creates a decoder for an already-opened audio file. */
 	static SoundDecoder *open_io(IO::Seekable &);
 
+	/** Restarts decoding from the beginning of the file. */
 	virtual void rewind() { seek(0); }
+
+	/** Sets decoding position expressed in PCM bytes.  This may involve seeking
+	to the beginning and skipping until the desired position is reached.*/
 	virtual void seek(unsigned) = 0;
+
+	/** Reads decoded sound data.  Length is specified in bytes. */
 	virtual unsigned read(char *, unsigned) = 0;
+
 	bool eof() const { return eof_flag; }
 
 	Format get_format() const { return format; }
 	unsigned get_frequency() const { return freq; }
+
+	/** Returns the total length of the sound data in bytes.  Some decoders may
+	not be able to provide this information. */
 	unsigned get_size() const { return size; }
 };
 
-- 
2.43.0