Document all APIs and reorganize methods for easier understanding

src/libdanbooru/servicebase.h

@@ -20,6 +20,13 @@
 #ifndef DANBOORU_SERVICEBASE_H
 #define DANBOORU_SERVICEBASE_H
 
+// Own
+
+#include "danbooru.h"
+#include "danboorupost.h"
+#include "danboorutag.h"
+#include "danboorupool.h"
+
 // Qt
 
 #include <QObject>
@@ -31,62 +38,293 @@
 
 #include <KImageCache>
 
-// Own
-
-#include "danbooru.h"
-#include "danboorupost.h"
-#include "danboorutag.h"
-
 
 namespace Danbooru
 {
 
+enum ApiType {
+    OriginalDanbooru = 7000,
+    KonachanDanbooru = 7001,
+    Gelbooru = 7002,
+    Unknown = 7003
+};
+
+enum SupportedOperation {
+        PostDownload = 6000,
+        TagDownload = 6001,
+        TagSearch = 6002,
+        PoolDownload = 6003,
+        RelatedTagSearch = 6004
+};
+
+Q_DECLARE_FLAGS(SupportedOperations, SupportedOperation)
+
 class DanbooruServiceBase: public QObject
 {
 
 Q_OBJECT
 
+private:
+
+    // URI functions
+
+    virtual const QLatin1String postUri() = 0;
+    virtual const QLatin1String poolUri() = 0;
+    virtual const QLatin1String artistUri() = 0;
+    virtual const QLatin1String poolDataUri() = 0;
+    virtual const QLatin1String relatedTagUri() = 0;
+
+    // member variables
+
+    QUrl m_url;
+    QString m_username;
+    QString m_password;
+    QSet<QString> m_blacklist;
+    DanbooruPost::Ratings m_maxRating;
+    int m_maxPosts;
+    int m_currentPage;
+    QStringList m_tags;
+
+    unsigned int m_postsToFetch; // To tell when to quit
+
+    KImageCache *m_cache; // Pixmap cache
+
 public:
 
-    enum SupportedOperations {
-        PostDownload = 6000,
-        TagDownload = 6001,
-        TagSearch = 6002,
-        PoolDownload = 6003,
-        RelatedTagSearch = 6004
-    }
-
     explicit DanbooruServiceBase();
-    ~DanbooruServiceBase();
+    virtual ~DanbooruServiceBase();
 
+    /////////////////////////////////////////////
+    // Functions shared with all implementations
+    /////////////////////////////////////////////
+
+    /**
+     * @brief Return the post ratings required for download.
+     *
+     * If a post does not meet the allowed rating, it is not downloaded (e.g., an Explicit post with
+     * only Safe and Questionable ratings).
+     *
+     * @return a QStringList with the allowed ratings.
+     */
     const QStringList allowedRatings() const;
-    const int apiVersion() const;
+
+    /**
+     * @brief Return the api type of the searvice.
+     **/
+    int apiType() const;
+
+    /**
+     * @brief Return the blacklisted tags for the service
+     *
+     * If a tag is in the blacklist, posts containing it will not be downloaded.
+     *
+     * @return a QSet containing the blacklisted tags,
+     **/
     const QSet<QString> blacklist() const;
+
+    /**
+     * @brief Return the current page.
+     *
+     * Danbooru APIs are heavily page-based due to their request limits (usually 100 posts per request).
+     * Therefore, to move to the next batch of posts, one needs to specify a "page" number. Service
+     * implementations need this to determine which set of posts to download.
+     *
+     * @return The current page number.
+     *
+     **/
     int currentPage() const;
 
-    virtual void getPostList() = 0;
+    /**
-    virtual void getPoolList() = 0;
+     * @return The maximum allowed rating for a post.
-    virtual void getPool(int poolId, int page = 1) = 0;
+     **/
-    virtual void getTagList(int limit = 10, QString name = "") = 0;
-    virtual void getRelatedTags(const QStringList &tags,
-                                DanbooruTag::TagType tagType = DanbooruTag::General) = 0;
-
     const DanbooruPost::Ratings maximumAllowedRating() const;
+
+    /**
+     * @return The number of posts downloaded for each page (max 100)
+     **/
+    int maxPosts() const;
+
+    /**
+     * @brief Move to the next post page and retrieve new posts.
+     *
+     **/
     Q_INVOKABLE void nextPostPage();
-    Q_INVOKABLE void nextPoolPage();
+
-    QStringList postTags() const;
+    /**
+     * @brief Move to the next pool page and retrieve new posts associated to the pool.
+     * The default implementation does nothing.
+     *
+     **/
+    Q_INVOKABLE virtual void nextPoolPage();
+
+    /**
+     * @return A QStringList containing the currently-selected tags
+     **/
+    QStringList postTags();
+
+    /**
+     * @brief Resets the service to the default state, clearing the page counters.
+     **/
     void reset();
 
+    /**
+     * @return The operations supported by the API.
+     **/
+    virtual SupportedOperations supportedOperations() const = 0;
+
+    ///////////////////////////////
+    // Common setters (non-virtual)
+    ///////////////////////////////
+
+    /**
+     * @brief Set blacklisted tags.
+     *
+     * Posts with blacklisted tags are not downloaded.
+     *
+     * @param blacklist A QSet<QString> including unwanted tags.
+     *
+     **/
     void setBlacklist(const QStringList &blacklist);
+
+    /**
+    * @brief Set the tag blacklist.
+    *
+    * If a tag is in the blacklist, posts tagged with it will not be downloaded.
+    *
+    **/
+    void setBlacklist(const QSet<QString> &blacklist);
+
+    /**
+     * @brief Set the board URL to connect to.
+     *
+     * @param url The URL to connect to.
+     */
     void setBoardUrl(const QUrl &url);
+
+    /**
+     * @brief Set the current page.
+     **/
     void setCurrentPage(int page);
+
+
+    /**
+     * @brief Set an image cache to use.
+     *
+     * @param cache A pointer to an instance of KImageCache.
+     */
     void setImageCache(KImageCache *cache);
+
+    /**
+     * @brief Set the maximum allowed rating for the board.
+     *
+     * Posts whose rating is higher than the maximuk allowed will not be
+     * downloaded.
+     *
+     **/
     void setMaximumAllowedRating(DanbooruPost::Rating rating);
+
+    /**
+     * @brief Set the maximum number of posts to download for each page.
+     **/
     void setMaxPosts(int number);
+
+    /**
+     * @brief Set the password used for login.
+     *
+     * @warning It should not be the password itself, but a SHA1 hash
+     *  with a specific salt (which is board-dependent; check their
+     *  API access rules).
+     *
+     * @param password The salted password to use.
+     *
+     **/
     void setPassword(const QString &password);
+
+    /**
+     * @brief Set the tags needed to fetch posts
+     *
+     * This basically sets the tags to "search" for: the way they are used
+     * is API-dependent.
+     *
+     * **/
     void setPostTags(const QStringList &tags);
+
+    /**
+     * @brief Set username for login.
+     *
+     * @param username The username to use.
+     *
+     **/
     void setUserName(const QString &username);
 
+    ////////////////////////////////////
+    // API specific operations (virtual)
+    ////////////////////////////////////
+
+    /**
+     * @brief Get posts from a Danbooru board.
+     *
+     * The default implementation does nothing.
+     *
+     **/
+    virtual void getPostList() = 0;
+
+    /**
+     * @brief Get a list of pools from a Danbooru board.
+     *
+     * The default implementation does nothing.
+     *
+     * @remarks
+     *      This does not actually retrieve pool contents, only their definitions.
+     *
+     **/
+    virtual void getPoolList() = 0;
+
+    /**
+     * @brief retrieve posts associated to a specific pool from a Danbooru board.
+     *
+     * Use this function when you want to actually retrieve posts associated to pools obtained through getPoolList.
+     *
+     * @param poolId the ID associated to the pool
+     * @param page the page containing posts (for pools with more than 100 posts).
+     *
+     * @remarks
+     *  This operation may not present in all Danbooru implementations.
+     */
+    virtual void getPool(int poolId, int page = 1) = 0;
+
+    /**
+     * @brief Get a list of tags from the board
+     *
+     * If name is supplied, a list of tags including the exact name of the
+     * tag is fetched from Danbooru, otherwise the most recent tags are
+     * retrieved.
+     *
+     * The tagDownloaded signal is emitted every time a tag has been
+     * retrieved.
+     *
+     * @param limit The number of tags to get.
+     * @param name The name of the tag to retrieve, or an empty string
+     *
+     * @remarks
+     *      May not be supported by all APIs.
+     *
+     **/
+    virtual void getTagList(int limit = 10, QString name = "") = 0;
+
+    /**
+     * @brief Get tags related to a specific, user supplied list.
+     *
+     * @param tags The tags to query for related terms
+     * @param tagType The type of tag to query for
+     *
+     * @remarks
+     *      May not be supported by all APIs.
+     *
+     **/
+    virtual void getRelatedTags(const QStringList &tags,
+                                DanbooruTag::TagType tagType = DanbooruTag::General) = 0;
+
 Q_SIGNALS:
 
     /**
@@ -136,6 +374,9 @@ Q_SIGNALS:
 
 };
 
+Q_DECLARE_OPERATORS_FOR_FLAGS(Danbooru::SupportedOperations)
+
+
 }
 
 #endif