[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    [syntax-highlighting] src/lib: API documentation for DefinitionDownloader
From:       Dominik Haumann <dhaumann () kde ! org>
Date:       2016-09-30 18:25:20
Message-ID: E1bq2Uq-0002yC-VH () code ! kde ! org
[Download RAW message or body]

Git commit a9e4c18a75074b17982c666522198096b7a1cc56 by Dominik Haumann.
Committed on 30/09/2016 at 18:25.
Pushed by dhaumann into branch 'master'.

API documentation for DefinitionDownloader

The header of this file is not installed right now, though.

M  +57   -0    src/lib/definitiondownloader.h

http://commits.kde.org/syntax-highlighting/a9e4c18a75074b17982c666522198096b7a1cc56

diff --git a/src/lib/definitiondownloader.h b/src/lib/definitiondownloader.h
index a7eea54..01bca2b 100644
--- a/src/lib/definitiondownloader.h
+++ b/src/lib/definitiondownloader.h
@@ -28,17 +28,74 @@ namespace SyntaxHighlighting {
 class DefinitionDownloaderPrivate;
 class Repository;
 
+/**
+ * Helper class to download definition file updates.
+ *
+ * With the DefinitionDownloader you can download new and update existing
+ * syntax highlighting definition files (xml files).
+ *
+ * An example that updates the highlighting Definition%s and prints the current
+ * update progress to the console may look as follows:
+ *
+ * @code
+ * auto downloader = new DefinitionDownloader(repo); // repo is a pointer to a Repository
+ *
+ * // print update progress to console
+ * QObject::connect(downloader, &DefinitionDownloader::informationMessage, [](const QString &msg) {
+ *     std::cout << qPrintable(msg) << std::endl;
+ * });
+ *
+ * // connect to signal done to delete the downloader later
+ * QObject::connect(downloader, &DefinitionDownloader::done,
+ *                  downloader, &DefinitionDownloader::deleteLater);
+ * downloader->start();
+ * @endcode
+ *
+ * @see Repository, Definition
+ */
 class KF5SYNTAXHIGHLIGHTING_EXPORT DefinitionDownloader : public QObject
 {
     Q_OBJECT
 public:
+    /**
+     * Constructor.
+     * The Repository @p repo is used as reference to compare the versions of
+     * the existing Definition%s with the ones that are available online.
+     *
+     * Optionally, @p parent is a pointer to the owner of this instance.
+     */
     explicit DefinitionDownloader(Repository *repo, QObject *parent = Q_NULLPTR);
+
+    /**
+     * Destructor.
+     */
     ~DefinitionDownloader();
 
+    /**
+     * Starts the update procedure.
+     * Once no more updates are available (i.e. either the local definition files
+     * are up-to-date, or all updates have been downloaded), the signal done()
+     * is emitted.
+     *
+     * During the update process, the signal informationMessage() can be used
+     * to display the current update progress to the user.
+     *
+     * @see done(), informationMessage()
+     */
     void start();
 
 Q_SIGNALS:
+    /**
+     * Prints the information about the current state of the definition files.
+     * If all files are up-to-date, this signal is emitted informing you that
+     * all highlighting files are up-to-date. If there are updates, this signal
+     * is emitted for each update being downloaded.
+     */
     void informationMessage(const QString &msg);
+
+    /**
+     * This signal is emitted when there are no pending downloads anymore.
+     */
     void done();
 
 private:
[prev in list] [next in list] [prev in thread] [next in thread]