From 698f321e698d9e02a9641ef5fbd2888d1f740a31 Mon Sep 17 00:00:00 2001 From: Tobias Doerffel Date: Sat, 7 Aug 2010 00:07:54 +0200 Subject: [PATCH] ResourceProvider+subclasses: added doxygen comments Documented the whole ResourceProvider class and important parts of the subclasses. --- include/LocalResourceProvider.h | 11 +++++++- include/ResourceProvider.h | 45 +++++++++++++++++++++++++++++-- include/UnifiedResourceProvider.h | 10 ++++++- include/WebResourceProvider.h | 11 +++++++- 4 files changed, 72 insertions(+), 5 deletions(-) diff --git a/include/LocalResourceProvider.h b/include/LocalResourceProvider.h index 0ffa56f0f..14d3feb45 100644 --- a/include/LocalResourceProvider.h +++ b/include/LocalResourceProvider.h @@ -1,7 +1,7 @@ /* * LocalResourceProvider.h - header file for LocalResourceProvider * - * Copyright (c) 2009 Tobias Doerffel + * Copyright (c) 2009-2010 Tobias Doerffel * * 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 diff --git a/include/ResourceProvider.h b/include/ResourceProvider.h index 49dec9a2e..f4d194995 100644 --- a/include/ResourceProvider.h +++ b/include/ResourceProvider.h @@ -1,7 +1,7 @@ /* * ResourceProvider.h - header file for ResourceProvider * - * Copyright (c) 2009 Tobias Doerffel + * Copyright (c) 2009-2010 Tobias Doerffel * * 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; diff --git a/include/UnifiedResourceProvider.h b/include/UnifiedResourceProvider.h index c5f385803..31c0d6cf2 100644 --- a/include/UnifiedResourceProvider.h +++ b/include/UnifiedResourceProvider.h @@ -1,7 +1,7 @@ /* * UnifiedResourceProvider.h - header file for UnifiedResourceProvider * - * Copyright (c) 2009 Tobias Doerffel + * Copyright (c) 2009-2010 Tobias Doerffel * * 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 diff --git a/include/WebResourceProvider.h b/include/WebResourceProvider.h index f583e9d13..0cd74f562 100644 --- a/include/WebResourceProvider.h +++ b/include/WebResourceProvider.h @@ -1,7 +1,7 @@ /* * WebResourceProvider.h - header file for WebResourceProvider * - * Copyright (c) 2009 Tobias Doerffel + * Copyright (c) 2009-2010 Tobias Doerffel * * 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