Add some docs for the musicbrainz stuff

src/musicbrainz/fingerprinter.h

@@ -25,10 +25,21 @@
 class QEventLoop;
 
 class Fingerprinter {
+  // Creates an OFA fingerprint from a song.
+  // Uses GStreamer to open and decode the file, also uses gstreamer's ofa
+  // element to generate the fingerprint.  The fingerprint identifies one
+  // particular encoding of a song.  Pass the fingerprint to MusicDNS to
+  // identify it.
+  // You should create one Fingerprinter for each file you want to fingerprint.
+  // This class works well with QtConcurrentMap.
+
 public:
   Fingerprinter(const QString& filename);
   ~Fingerprinter();
 
+  // Creates a fingerprint from the song.  This method is blocking, so you want
+  // to call it in another thread.  Returns an empty string if no fingerprint
+  // could be created.
   QString CreateFingerprint();
 
 private:

src/musicbrainz/musicbrainzclient.h

@@ -28,6 +28,12 @@ class QXmlStreamReader;
 class MusicBrainzClient : public QObject {
   Q_OBJECT
 
+  // Gets metadata for a particular PUID.
+  // A PUID is created from a fingerprint using MusicDnsClient.
+  // You can create one MusicBrainzClient and make multiple requests using it.
+  // IDs are provided by the caller when a request is started and included in
+  // the Finished signal - they have no meaning to MusicBrainzClient.
+
 public:
   MusicBrainzClient(QObject* parent = 0);
 
@@ -42,8 +48,16 @@ public:
   };
   typedef QList<Result> ResultList;
 
+  // Starts a request and returns immediately.  Finished() will be emitted
+  // later with the same ID.
   void Start(int id, const QString& puid);
+
+  // Cancels the request with the given ID.  Finished() will never be emitted
+  // for that ID.  Does nothing if there is no request with the given ID.
   void Cancel(int id);
+
+  // Cancels all requests.  Finished() will never be emitted for any pending
+  // requests.
   void CancelAll();
 
 signals:

src/musicbrainz/musicdnsclient.h

@@ -27,11 +27,27 @@ class QNetworkReply;
 class MusicDnsClient : public QObject {
   Q_OBJECT
 
+  // Gets a PUID from an OFA fingerprint.
+  // A fingerprint identifies one particular encoding of a song and is created
+  // by Fingerprinter.  A PUID identifies the actual song and can be passed to
+  // Musicbrainz to get metadata.
+  // You can create one MusicDnsClient and make multiple requests using it.
+  // IDs are provided by the caller when a request is started and included in
+  // the Finished signal - they have no meaning to MusicDnsClient.
+
 public:
   MusicDnsClient(QObject* parent = 0);
 
+  // Starts a request and returns immediately.  Finished() will be emitted
+  // later with the same ID.
   void Start(int id, const QString& fingerprint, int duration_msec);
+
+  // Cancels the request with the given ID.  Finished() will never be emitted
+  // for that ID.  Does nothing if there is no request with the given ID.
   void Cancel(int id);
+
+  // Cancels all requests.  Finished() will never be emitted for any pending
+  // requests.
   void CancelAll();
 
 signals:

src/musicbrainz/tagfetcher.h

@@ -29,6 +29,9 @@ class MusicDnsClient;
 class TagFetcher : public QObject {
   Q_OBJECT
 
+  // High level interface to Fingerprinter, MusicDnsClient and
+  // MusicBrainzClient.
+
 public:
   TagFetcher(QObject* parent = 0);