ResourceProvider+subclasses: added doxygen comments

Documented the whole ResourceProvider class and important parts of the
subclasses.

include/LocalResourceProvider.h

@@ -1,7 +1,7 @@
 /*
  * LocalResourceProvider.h - header file for LocalResourceProvider
  *
- * Copyright (c) 2009 Tobias Doerffel <tobydox/at/users.sourceforge.net>
+ * Copyright (c) 2009-2010 Tobias Doerffel <tobydox/at/users.sourceforge.net>
  *
  * This file is part of Linux MultiMedia Studio - http://lmms.sourceforge.net
  *
@@ -32,6 +32,15 @@
 #include "ResourceItem.h"
 
 
+/*! \brief The LocalResourceProvider class provides a ResourceProvider
+ * implementation which serves data from local files.
+ *
+ * This class crawls a given directory and provides a ResourceDB with all
+ * retrieved information inside. Additionally it monitors all (sub-)directories
+ * for changes and immediately updates the database. #fetchData() simply reads
+ * the according local file.
+ */
+
 class EXPORT LocalResourceProvider : public ResourceProvider
 {
 	Q_OBJECT

include/ResourceProvider.h

@@ -1,7 +1,7 @@
 /*
  * ResourceProvider.h - header file for ResourceProvider
  *
- * Copyright (c) 2009 Tobias Doerffel <tobydox/at/users.sourceforge.net>
+ * Copyright (c) 2009-2010 Tobias Doerffel <tobydox/at/users.sourceforge.net>
  *
  * This file is part of Linux MultiMedia Studio - http://lmms.sourceforge.net
  *
@@ -33,33 +33,74 @@ class ResourceDB;
 class ResourceItem;
 
 
+/*! \brief The ResourceProvider class provides an abstract API for various
+ * backends that can serve a resource index and data of individual ResourceItems
+ *
+ * A ResourceProvider abstracts I/O of resource related data. It both serves
+ * a resource index (in form of a ResourceDB) and functions such as
+ * #fetchData(). Subclasses have to reimplement the pure virtual functions.
+ */
+
 class ResourceProvider : public QObject
 {
 	Q_OBJECT
 public:
+	/*! \brief Constructs a ResourceProvider object.
+	* \param url A generic URL (can be e.g. a local path or a web URL)
+	*/
 	ResourceProvider( const QString & _url );
+	/*! \brief Destroys the ResourceProvider object. */
 	virtual ~ResourceProvider();
 
+	/*! \brief Returns the name of subclass.
+	*
+	* Used for example for generating a unique file name for the local cache
+	* file. */
 	virtual QString providerName() const = 0;
+
+	/*! \brief Triggers action to update the database.
+	*
+	* Subclasses can start to update their index e.g. by directory crawling
+    * or downloading an index file from somewhere. */
 	virtual void updateDatabase() = 0;
+
+	/*! \brief Determines size of a ResourceItem (e.g. by stat()ing local file).
+	* \param item The ResourceItem whose size to determine
+    * \ret The determined size of the passed ResourceItem */
 	virtual int dataSize( const ResourceItem * _item ) const = 0;
+
+	/*! \brief Fetches data represented by a ResourceItem.
+	* \param item The item whose data to fetch
+	* \param maxSize A limit for the data size to fetch, -1 for no limit */
 	virtual QByteArray fetchData( const ResourceItem * _item,
 					int _maxSize = -1 ) const = 0;
-	// return wether this provider provides local resources
+
+	/*! \brief Returns wether this provider provides local resources.
+	*
+	* This can be important for code which fetches data using a ResourceProvider
+	* and which wants to know whether it should cache the fetched data somehow. */
 	virtual bool isLocal() const = 0;
 
+	/*! \brief Returns whether the ResourceProvider base class should manage
+	* caching of the database.
+	*
+	* Some special ResourceProvider subclasses that do some kind of proxying
+	* should overload this and return false. */
 	virtual bool cacheDatabase() const
 	{
 		return true;
 	}
 
+	/*! \brief Returns URL of this ResourceProvider object. */
 	inline const QString & url() const
 	{
 		return m_url;
 	}
 
+	/*! \brief Returns full path to local cache file for this ResourceProvider. */
 	QString localCacheFile() const;
 
+	/*! \brief Returns pointer to internal ResourceDB. */
 	ResourceDB * database()
 	{
 		return m_database;

include/UnifiedResourceProvider.h

@@ -1,7 +1,7 @@
 /*
  * UnifiedResourceProvider.h - header file for UnifiedResourceProvider
  *
- * Copyright (c) 2009 Tobias Doerffel <tobydox/at/users.sourceforge.net>
+ * Copyright (c) 2009-2010 Tobias Doerffel <tobydox/at/users.sourceforge.net>
  *
  * This file is part of Linux MultiMedia Studio - http://lmms.sourceforge.net
  *
@@ -29,6 +29,14 @@
 #include "ResourceItem.h"
 
 
+/*! \brief The UnifiedResourceProvider class merges a given set of ResourceDB's
+ * into one ResourceDB.
+ *
+ * This provider usually is used as the top level provider whose database
+ * contains all available resources (various local directories and various
+ * online catalogues).
+ */
+
 class UnifiedResourceProvider : public ResourceProvider
 {
 	Q_OBJECT

include/WebResourceProvider.h

@@ -1,7 +1,7 @@
 /*
  * WebResourceProvider.h - header file for WebResourceProvider
  *
- * Copyright (c) 2009 Tobias Doerffel <tobydox/at/users.sourceforge.net>
+ * Copyright (c) 2009-2010 Tobias Doerffel <tobydox/at/users.sourceforge.net>
  *
  * This file is part of Linux MultiMedia Studio - http://lmms.sourceforge.net
  *
@@ -36,6 +36,15 @@ class QBuffer;
 class QNetworkReply;
 
 
+/*! \brief The WebResourceProvider class provides a ResourceProvider
+ * implementation which serves data from the internet (currently
+ * specific to LSP only).
+ *
+ * Most of this class is network management code (quite highlevel thanks to
+ * QtNetwork though). Besides that it translates web resource index files into
+ * a ResourceDB and fetches files by given hash.
+ */
+
 class WebResourceProvider : public ResourceProvider
 {
 	Q_OBJECT