From ed874ed00af6e795debf6614a92f0c5944581676 Mon Sep 17 00:00:00 2001
From: James Graham <james.h.graham@protonmail.com>
Date: Sun, 23 Apr 2023 08:24:09 +0000
Subject: [PATCH] Document clipboard

---
 src/clipboard.cpp |  8 ++++----
 src/clipboard.h   | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/src/clipboard.cpp b/src/clipboard.cpp
index a85c91aeb..1fbef7878 100644
--- a/src/clipboard.cpp
+++ b/src/clipboard.cpp
@@ -62,10 +62,10 @@ QString Clipboard::saveImage(QString localPath) const
 void Clipboard::saveText(QString message)
 {
     static QRegularExpression re(QStringLiteral("<[^>]*>"));
-    auto *mineData = new QMimeData; // ownership is transferred to clipboard
-    mineData->setHtml(message);
-    mineData->setText(message.replace(re, QString()));
-    m_clipboard->setMimeData(mineData);
+    auto *mimeData = new QMimeData; // ownership is transferred to clipboard
+    mimeData->setHtml(message);
+    mimeData->setText(message.replace(re, QString()));
+    m_clipboard->setMimeData(mimeData);
 }
 
 void Clipboard::setImage(const QUrl &url)
diff --git a/src/clipboard.h b/src/clipboard.h
index 2d3a4dd7e..b7ed9094c 100644
--- a/src/clipboard.h
+++ b/src/clipboard.h
@@ -9,23 +9,60 @@ class QClipboard;
 class QImage;
 
 /**
+ * @class Clipboard
+ *
  * Clipboard proxy
+ *
+ * Used to set and retrieve content from the clipboard.
  */
 class Clipboard : public QObject
 {
     Q_OBJECT
+
+    /**
+     * @brief Whether the current clipboard content is an image.
+     */
     Q_PROPERTY(bool hasImage READ hasImage NOTIFY imageChanged)
+
+    /**
+     * @brief Return the current clipboard content image.
+     *
+     * Returns a null image if the clipboard does not contain an image or if it
+     * contains an image in an unsupported image format.
+     */
     Q_PROPERTY(QImage image READ image NOTIFY imageChanged)
 
 public:
     explicit Clipboard(QObject *parent = nullptr);
 
     [[nodiscard]] bool hasImage() const;
+
     [[nodiscard]] QImage image() const;
 
+    /**
+     * @brief Save the current clipboard image to file.
+     *
+     * If the clipboard does not contain an image or if it contains an image in an
+     * unsupported image format nothing happens.
+     *
+     * The given file path must be both valid and local or nothing happens.
+     *
+     * @param localPath the path to save the image. A default path for the app cache
+     *                  will be used if available and this is empty.
+     *
+     * @return A QString with the path that the image was saved to. The string will
+     *         be empty if nothing was saved.
+     */
     Q_INVOKABLE QString saveImage(QString localPath = {}) const;
 
+    /**
+     * @brief Set the clipboard content to the input message.
+     */
     Q_INVOKABLE void saveText(QString message);
+
+    /**
+     * @brief Set the clipboard content to the input image.
+     */
     Q_INVOKABLE void setImage(const QUrl &image);
 
 private: