Document SyncthingService

connector/syncthingservice.cpp

@@ -24,6 +24,18 @@ using namespace CppUtilities;
 
 namespace Data {
 
+/*!
+ * \class SyncthingService
+ * \brief The SyncthingService class controls and monitors a Syncthing as systemd user service.
+ * \remarks Internally systemd's D-Bus interface is used. So the service "org.freedesktop.systemd1" must
+ *          be running on the user-session D-Bus.
+ *
+ * This class is actually not Syncthing-specific. It could be used to control and monitor any systemd
+ * user service.
+ */
+
+/// \cond
+
 QDBusArgument &operator<<(QDBusArgument &argument, const ManagerDBusUnitFileChange &unitFileChange)
 {
     argument.beginStructure();
@@ -51,6 +63,11 @@ OrgFreedesktopLogin1ManagerInterface *SyncthingService::s_loginManager = nullptr
 DateTime SyncthingService::s_lastWakeUp = DateTime();
 bool SyncthingService::s_fallingAsleep = false;
 
+/// \endcond
+
+/*!
+ * \brief Creates a new SyncthingService instance.
+ */
 SyncthingService::SyncthingService(QObject *parent)
     : QObject(parent)
     , m_unit(nullptr)
@@ -107,6 +124,9 @@ SyncthingService::SyncthingService(QObject *parent)
 #endif
 }
 
+/*!
+ * \brief Sets the \a unitName of the systemd user service to be controlled/monitored, e.g. "syncthing.service".
+ */
 void SyncthingService::setUnitName(const QString &unitName)
 {
     if (m_unitName == unitName) {
@@ -128,6 +148,11 @@ void SyncthingService::setUnitName(const QString &unitName)
     emit unitNameChanged(unitName);
 }
 
+/*!
+ * \brief Returns whether systemd (and specificly its D-Bus interface for user services) is available.
+ * \remarks The availability might not be instantly detected and may change at any time. Use the systemdAvailableChanged()
+ *          to react to availability changes.
+ */
 bool SyncthingService::isSystemdAvailable() const
 {
 #ifndef LIB_SYNCTHING_CONNECTOR_SERVICE_MOCKED
@@ -137,6 +162,13 @@ bool SyncthingService::isSystemdAvailable() const
 #endif
 }
 
+/*!
+ * \brief Returns whether the unit specified with \a unitName is available.
+ * \remarks
+ * - The availability might not be instantly detected and may change at any time. Use the unitAvailableChanged()
+ *   to react to availability changes.
+ * - Unless this function returns true the other unit-related functions will return false/empty values.
+ */
 bool SyncthingService::isUnitAvailable() const
 {
 #ifndef LIB_SYNCTHING_CONNECTOR_SERVICE_MOCKED
@@ -146,6 +178,9 @@ bool SyncthingService::isUnitAvailable() const
 #endif
 }
 
+/*!
+ * \brief Returns whether \a activeSince or the last standby-wake-up is longer ago than \a atLeastSeconds.
+ */
 bool SyncthingService::isActiveWithoutSleepFor(DateTime activeSince, unsigned int atLeastSeconds)
 {
     if (!atLeastSeconds) {
@@ -159,6 +194,9 @@ bool SyncthingService::isActiveWithoutSleepFor(DateTime activeSince, unsigned in
     return ((now - activeSince).totalSeconds() > atLeastSeconds) && (s_lastWakeUp.isNull() || ((now - s_lastWakeUp).totalSeconds() > atLeastSeconds));
 }
 
+/*!
+ * \brief Starts the unit if \a running is true and stops the unit if \a running is false.
+ */
 void SyncthingService::setRunning(bool running)
 {
 #ifndef LIB_SYNCTHING_CONNECTOR_SERVICE_MOCKED
@@ -171,6 +209,9 @@ void SyncthingService::setRunning(bool running)
 #endif
 }
 
+/*!
+ * \brief Enables the unit if \a enabled is true and disables the unit if \a enabled is false.
+ */
 void SyncthingService::setEnabled(bool enabled)
 {
 #ifndef LIB_SYNCTHING_CONNECTOR_SERVICE_MOCKED
@@ -182,6 +223,9 @@ void SyncthingService::setEnabled(bool enabled)
 #endif
 }
 
+/*!
+ * \brief Handles when a new unit is added to react if it matches the name of the unit we're monitoring.
+ */
 void SyncthingService::handleUnitAdded(const QString &unitName, const QDBusObjectPath &unitPath)
 {
     if (unitName == m_unitName) {
@@ -189,6 +233,9 @@ void SyncthingService::handleUnitAdded(const QString &unitName, const QDBusObjec
     }
 }
 
+/*!
+ * \brief Handles when a unit is removed to react if it matches the name of the unit we're monitoring.
+ */
 void SyncthingService::handleUnitRemoved(const QString &unitName, const QDBusObjectPath &unitPath)
 {
     Q_UNUSED(unitPath)
@@ -197,6 +244,9 @@ void SyncthingService::handleUnitRemoved(const QString &unitName, const QDBusObj
     }
 }
 
+/*!
+ * \brief Consumes the results of the s_manager->GetUnit() call (in setUnitName()).
+ */
 void SyncthingService::handleUnitGet(QDBusPendingCallWatcher *watcher)
 {
     watcher->deleteLater();
@@ -209,6 +259,9 @@ void SyncthingService::handleUnitGet(QDBusPendingCallWatcher *watcher)
     setUnit(unitReply.value());
 }
 
+/*!
+ * \brief Handles when properties of the monitored unit change.
+ */
 void SyncthingService::handlePropertiesChanged(
     const QString &interface, const QVariantMap &changedProperties, const QStringList &invalidatedProperties)
 {
@@ -249,6 +302,9 @@ void SyncthingService::handlePropertiesChanged(
         m_description, &SyncthingService::descriptionChanged, QStringLiteral("Description"), changedProperties, invalidatedProperties);
 }
 
+/*!
+ * \brief Handles D-Bus errors.
+ */
 void SyncthingService::handleError(const char *context, QDBusPendingCallWatcher *watcher)
 {
     watcher->deleteLater();
@@ -258,6 +314,9 @@ void SyncthingService::handleError(const char *context, QDBusPendingCallWatcher
     }
 }
 
+/*!
+ * \brief Handles when the service availability changes.
+ */
 void SyncthingService::handleServiceRegisteredChanged(const QString &service)
 {
     if (service == s_manager->service()) {
@@ -265,6 +324,9 @@ void SyncthingService::handleServiceRegisteredChanged(const QString &service)
     }
 }
 
+/*!
+ * \brief Logs the moment before when standby is enabled and the time of the last standby-wakeup.
+ */
 void SyncthingService::handlePrepareForSleep(bool rightBefore)
 {
     if (!(s_fallingAsleep = rightBefore)) {
@@ -272,6 +334,9 @@ void SyncthingService::handlePrepareForSleep(bool rightBefore)
     }
 }
 
+/*!
+ * \brief Internal helper to handle property changes for QString-properties.
+ */
 bool SyncthingService::handlePropertyChanged(QString &variable, void (SyncthingService::*signal)(const QString &), const QString &propertyName,
     const QVariantMap &changedProperties, const QStringList &invalidatedProperties)
 {
@@ -290,6 +355,9 @@ bool SyncthingService::handlePropertyChanged(QString &variable, void (SyncthingS
     return false;
 }
 
+/*!
+ * \brief Internal helper to handle property changes for DateTime-properties.
+ */
 bool SyncthingService::handlePropertyChanged(
     DateTime &variable, const QString &propertyName, const QVariantMap &changedProperties, const QStringList &invalidatedProperties)
 {
@@ -308,11 +376,17 @@ bool SyncthingService::handlePropertyChanged(
     return false;
 }
 
+/*!
+ * \brief Registers error handler for D-Bus errors.
+ */
 void SyncthingService::registerErrorHandler(const QDBusPendingCall &call, const char *context)
 {
     connect(new QDBusPendingCallWatcher(call, this), &QDBusPendingCallWatcher::finished, bind(&SyncthingService::handleError, this, context, _1));
 }
 
+/*!
+ * \brief Sets the current unit data.
+ */
 void SyncthingService::setUnit(const QDBusObjectPath &objectPath)
 {
     // cleanup
@@ -335,6 +409,9 @@ void SyncthingService::setUnit(const QDBusObjectPath &objectPath)
     connect(m_properties, &OrgFreedesktopDBusPropertiesInterface::PropertiesChanged, this, &SyncthingService::handlePropertiesChanged);
 }
 
+/*!
+ * \brief Updates the properties for the current unit.
+ */
 void SyncthingService::setProperties(
     bool unitAvailable, const QString &activeState, const QString &subState, const QString &unitFileState, const QString &description)
 {

connector/syncthingservice.h

@@ -127,96 +127,162 @@ private:
     bool m_unitAvailable;
 };
 
+/*!
+ * \brief Returns the name of the systemd user service unit to be controlled/monitored, e.g. "syncthing.service".
+ */
 inline const QString &SyncthingService::unitName() const
 {
     return m_unitName;
 }
 
+/*!
+ * \brief Returns the active state of the unit.
+ * \remarks The unit must be available, \sa SyncthingService::isUnitAvailable().
+ */
 inline const QString &SyncthingService::activeState() const
 {
     return m_activeState;
 }
 
+/*!
+ * \brief Returns the sub state of the unit.
+ * \remarks The unit must be available, \sa SyncthingService::isUnitAvailable().
+ */
 inline const QString &SyncthingService::subState() const
 {
     return m_subState;
 }
 
+/*!
+ * \brief Returns the unit file state.
+ * \remarks The unit must be available, \sa SyncthingService::isUnitAvailable().
+ */
 inline const QString &SyncthingService::unitFileState() const
 {
     return m_unitFileState;
 }
 
+/*!
+ * \brief Returns the unit description.
+ * \remarks The unit must be available, \sa SyncthingService::isUnitAvailable().
+ */
 inline const QString &SyncthingService::description() const
 {
     return m_description;
 }
 
+/*!
+ * \brief Returns whether the unit is running.
+ * \remarks The unit must be available, \sa SyncthingService::isUnitAvailable().
+ */
 inline bool SyncthingService::isRunning() const
 {
     return m_activeState == QLatin1String("active") && m_subState == QLatin1String("running");
 }
 
+/*!
+ * \brief Starts the unit.
+ */
 inline void SyncthingService::start()
 {
     setRunning(true);
 }
 
+/*!
+ * \brief Stops the unit.
+ */
 inline void SyncthingService::stop()
 {
     setRunning(false);
 }
 
+/*!
+ * \brief Toggles the running state.
+ */
 inline void SyncthingService::toggleRunning()
 {
     setRunning(!isRunning());
 }
 
+/*!
+ * \brief Returns whether the unit is enabled.
+ * \remarks The unit must be available, \sa SyncthingService::isUnitAvailable().
+ */
 inline bool SyncthingService::isEnabled() const
 {
     return m_unitFileState == QLatin1String("enabled");
 }
 
+/*!
+ * \brief Returns whether the unit has been manually stopped via stop(), toggleRunning() or setRunning().
+ */
 inline bool SyncthingService::isManuallyStopped() const
 {
     return m_manuallyStopped;
 }
 
+/*!
+ * \brief Returns since when the unit is active.
+ */
 inline CppUtilities::DateTime SyncthingService::activeSince() const
 {
     return m_activeSince;
 }
 
+/*!
+ * \brief Returns whether the unit has been active for at least \a atLeastSeconds.
+ * \remarks An interruption due to standby is *not* taken into account.
+ */
 inline bool SyncthingService::isActiveFor(unsigned int atLeastSeconds) const
 {
     return !m_activeSince.isNull() && (CppUtilities::DateTime::gmtNow() - m_activeSince).totalSeconds() > atLeastSeconds;
 }
 
+/*!
+ * \brief Returns whether the unit has been active for at least \a atLeastSeconds.
+ * \remarks An interruption due to standby is taken into account. So if the last standby-wakeup was less than \a atLeastSeconds
+ *          ago this function returns false regardless of the unit's activeness.
+ */
 inline bool SyncthingService::isActiveWithoutSleepFor(unsigned int atLeastSeconds) const
 {
     return isActiveWithoutSleepFor(m_activeSince, atLeastSeconds);
 }
 
+/*!
+ * \brief Returns when the last standby-wakeup happend.
+ */
 inline CppUtilities::DateTime SyncthingService::lastWakeUp()
 {
     return s_lastWakeUp;
 }
 
+/*!
+ * \brief Enables the unit.
+ */
 inline void SyncthingService::enable()
 {
     setEnabled(true);
 }
 
+/*!
+ * \brief Disables the unit.
+ */
 inline void SyncthingService::disable()
 {
     setEnabled(false);
 }
 
+/*!
+ * \brief Returns the SyncthingService instance which has previously been assigned via SyncthingService::setMainInstance().
+ */
 inline SyncthingService *SyncthingService::mainInstance()
 {
     return s_mainInstance;
 }
 
+/*!
+ * \brief Assigns the "main" SyncthingService instance.
+ */
 inline void SyncthingService::setMainInstance(SyncthingService *mainInstance)
 {
     s_mainInstance = mainInstance;