From f7c3ceaecef9d4054d2bf54ec46885ca58077e03 Mon Sep 17 00:00:00 2001
From: Martchus <martchus@gmx.net>
Date: Thu, 31 Dec 2020 02:30:05 +0100
Subject: [PATCH] Improve documentation of connector library

---
 connector/syncthingconnection.cpp     |  7 +++----
 connector/syncthingconnection.h       |  3 ++-
 connector/syncthingconnectionstatus.h |  9 ++++++++-
 connector/syncthingdev.h              | 10 +++++++++-
 4 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/connector/syncthingconnection.cpp b/connector/syncthingconnection.cpp
index 3148784..0cf78d7 100644
--- a/connector/syncthingconnection.cpp
+++ b/connector/syncthingconnection.cpp
@@ -938,13 +938,12 @@ void SyncthingConnection::handleAdditionalRequestCanceled()
 }
 
 /*!
- * \brief Internally called to recalculate the overall connection status, eg. after the status of a directory
+ * \brief Internally called to recalculate the overall connection status, e.g. after the status of a directory
  *        changed.
  * \remarks
  * - This is achieved by simply setting the status to idle. setStatus() will calculate the specific status.
  * - If not connected, this method does nothing. This is important, because when this method is called when
- *   establishing a connection (and the status is hence still disconnected) timers for polling would be
- *   killed.
+ *   establishing a connection (and the status is hence still disconnected) timers for polling would be killed.
  */
 void SyncthingConnection::recalculateStatus()
 {
@@ -1018,7 +1017,7 @@ void SyncthingConnection::recalculateStatus()
 
 /*!
  * \fn SyncthingConnection::statusChanged()
- * \brief Indicates the status of the connection changed.
+ * \brief Indicates the status of the connection changed (status(), hasOutOfSyncDirs()).
  */
 
 /*!
diff --git a/connector/syncthingconnection.h b/connector/syncthingconnection.h
index 1ce9562..3757de1 100644
--- a/connector/syncthingconnection.h
+++ b/connector/syncthingconnection.h
@@ -427,7 +427,8 @@ inline QString SyncthingConnection::statusText() const
 }
 
 /*!
- * \brief Returns the connection status.
+ * \brief Returns the (pre-computed) connection status.
+ * \sa See SyncthingConnection::setStatus() and SyncthingStatus for details how it is computed.
  */
 inline SyncthingStatus SyncthingConnection::status() const
 {
diff --git a/connector/syncthingconnectionstatus.h b/connector/syncthingconnectionstatus.h
index 9be42a7..2959dcc 100644
--- a/connector/syncthingconnectionstatus.h
+++ b/connector/syncthingconnectionstatus.h
@@ -17,7 +17,14 @@ enum class SyncthingStatus { Disconnected, Reconnecting, Idle, Scanning, Paused,
 Q_ENUM_NS(SyncthingStatus)
 #endif
 
-enum class SyncthingErrorCategory { OverallConnection, SpecificRequest, Parsing };
+/*!
+ * \brief The SyncthingErrorCategory enum classifies different errors related to the SyncthingConnection class.
+ */
+enum class SyncthingErrorCategory {
+    OverallConnection, /**< an error affecting the overall connection */
+    SpecificRequest, /**< an error only affecting a specific request */
+    Parsing, /**< an error when parsing Syncthing's response as a JSON document */
+};
 #if (QT_VERSION >= QT_VERSION_CHECK(5, 8, 0))
 Q_ENUM_NS(SyncthingErrorCategory)
 #endif
diff --git a/connector/syncthingdev.h b/connector/syncthingdev.h
index 53f7cfe..6dc5754 100644
--- a/connector/syncthingdev.h
+++ b/connector/syncthingdev.h
@@ -19,7 +19,15 @@ namespace Data {
 /// \brief The SyncthingDevStatus enum represents a Syncthing device status.
 /// \remarks The device status is not directly provided by Syncthing and instead deduced by this library from
 ///          other information and events.
-enum class SyncthingDevStatus { Unknown, Disconnected, OwnDevice, Idle, Synchronizing, OutOfSync, Rejected };
+enum class SyncthingDevStatus {
+    Unknown, /**< device status is unknown */
+    Disconnected, /**< device is disconnected */
+    OwnDevice, /**< device is the own device; the own device will always have this status assigned */
+    Idle, /**< device is connected and all shared directories are up-to-date on its end */
+    Synchronizing, /**< device is connected but not all shared directories are up-to-date on its end */
+    OutOfSync, /**< device is connected but not all shared directories are up-to-date on its end due to an error (never set so far; seems not possible to determine) */
+    Rejected, /**< device is rejected */
+};
 
 QString statusString(SyncthingDevStatus status);