From 0e50b51a63b0ecf7c74a0f72dd3a2391d72676af Mon Sep 17 00:00:00 2001 From: Dale Glass Date: Tue, 1 Nov 2022 17:01:16 +0100 Subject: [PATCH] Improve documentation --- libraries/shared/src/SettingHandle.h | 114 +++++++++++++++++++++++++- libraries/shared/src/SettingManager.h | 62 ++++++++++++++ 2 files changed, 174 insertions(+), 2 deletions(-) diff --git a/libraries/shared/src/SettingHandle.h b/libraries/shared/src/SettingHandle.h index f81c509c5b..0bddf5b4da 100644 --- a/libraries/shared/src/SettingHandle.h +++ b/libraries/shared/src/SettingHandle.h @@ -116,29 +116,99 @@ private: }; namespace Setting { + + /** + * @brief Handle to a setting of type T. + * + * This creates an object that manipulates a setting in the settings system. Changes will be written + * to the configuration file at some point controlled by Setting::Manager. + * + * @tparam T Type of the setting. + */ template class Handle : public Interface { public: + + /** + * @brief Construct handle to a setting + * + * @param key The key corresponding to the setting in the settings file. Eg, 'shadowsEnabled' + */ Handle(const QString& key) : Interface(key) {} + + /** + * @brief Construct a handle to a setting + * + * @param path Path to the key corresponding to the setting in the settings file. Eg, QStringList() << group << key + */ Handle(const QStringList& path) : Interface(path.join("/")) {} + /** + * @brief Construct handle to a setting with a default value + * + * @param key The key corresponding to the setting in the settings file. Eg, 'shadowsEnabled' + * @param defaultValue Default value for this setting + */ Handle(const QString& key, const T& defaultValue) : Interface(key), _defaultValue(defaultValue) {} + + /** + * @brief Construct a handle to a setting with a default value + * + * @param path Path to the key corresponding to the setting in the settings file. Eg, QStringList() << group << key + * @param defaultValue Default value for this setting + */ Handle(const QStringList& path, const T& defaultValue) : Handle(path.join("/"), defaultValue) {} + /** + * @brief Construct a handle to a deprecated setting + * + * If used, a warning will written to the log. + * + * @param key The key corresponding to the setting in the settings file. Eg, 'shadowsEnabled' + * @return Handle The handle object + */ static Handle Deprecated(const QString& key) { Handle handle = Handle(key); handle.deprecate(); return handle; } + + /** + * @brief Construct a handle to a deprecated setting + * + * If used, a warning will written to the log. + * + * @param path Path to the key corresponding to the setting in the settings file. Eg, QStringList() << group << key + * @return Handle The handle object + */ static Handle Deprecated(const QStringList& path) { return Deprecated(path.join("/")); } + /** + * @brief Construct a handle to a deprecated setting with a default value + * + * If used, a warning will written to the log. + * + * @param key The key corresponding to the setting in the settings file. Eg, 'shadowsEnabled' + * @param defaultValue Default value for this setting + * @return Handle The handle object + */ static Handle Deprecated(const QString& key, const T& defaultValue) { Handle handle = Handle(key, defaultValue); handle.deprecate(); return handle; } + + /** + * @brief Construct a handle to a deprecated setting with a default value + * + * If used, a warning will written to the log. + * + * @param path Path to the key corresponding to the setting in the settings file. Eg, QStringList() << group << key + * @param defaultValue Default value for this setting + * @return Handle The handle object + */ static Handle Deprecated(const QStringList& path, const T& defaultValue) { return Deprecated(path.join("/"), defaultValue); } @@ -147,32 +217,66 @@ namespace Setting { deinit(); } - // Returns setting value, returns its default value if not found + /** + * @brief Returns the value of the setting, or the default value if not found + * + * @return T Value of the associated setting + */ T get() const { return get(_defaultValue); } - // Returns setting value, returns other if not found + /** + * @brief Returns the value of the setting, or 'other' if not found. + * + * @param other Value to return if the setting is not set + * @return T Value of the associated setting + */ T get(const T& other) const { maybeInit(); return (_isSet) ? _value : other; } + /** + * @brief Returns whether the setting is set to a value + * + * @return true The setting has a value + * @return false The setting has no value + */ bool isSet() const { maybeInit(); return _isSet; } + /** + * @brief Returns the default value for this setting + * + * @return const T& Default value for this setting + */ const T& getDefault() const { return _defaultValue; } + /** + * @brief Sets the value to the default + * + */ void reset() { set(_defaultValue); } + /** + * @brief Set the setting to the specified value. + * + * The value will be stored in the configuration file. + * + * @param value Value to set the setting to. + */ void set(const T& value) { maybeInit(); + + // qCDebug(settings_handle) << "Setting" << this->getKey() << "to" << value; + if ((!_isSet && (value != _defaultValue)) || _value != value) { _value = value; _isSet = true; @@ -183,6 +287,12 @@ namespace Setting { } } + /** + * @brief Remove the value from the setting + * + * This returns the setting to an unset state. If read, it will be read as the default value. + * + */ void remove() { maybeInit(); if (_isSet) { diff --git a/libraries/shared/src/SettingManager.h b/libraries/shared/src/SettingManager.h index d0ea084ac2..f62164db0e 100644 --- a/libraries/shared/src/SettingManager.h +++ b/libraries/shared/src/SettingManager.h @@ -109,22 +109,84 @@ namespace Setting { void customDeleter() override; + /** + * @brief Returns the filename where the config file will be written + * + * @return QString Path to the config file + */ QString fileName() const; + + /** + * @brief Remove a configuration key + * + * @param key Key to remove + */ void remove(const QString &key); + + /** + * @brief Lists all keys in the configuration + * + * @return QStringList List of keys + */ QStringList allKeys() const; + + /** + * @brief Returns whether a key is part of the configuration + * + * @param key Key to look for + * @return true Key is in the configuration + * @return false Key isn't in the configuration + */ bool contains(const QString &key) const; + + /** + * @brief Set a setting to a value + * + * @param key Setting to set + * @param value Value + */ void setValue(const QString &key, const QVariant &value); + + /** + * @brief Returns the value of a setting + * + * @param key Setting to look for + * @param defaultValue Default value to return, if the setting has no value + * @return QVariant Current value of the setting, of defaultValue. + */ QVariant value(const QString &key, const QVariant &defaultValue = QVariant()) const; protected: + /** + * @brief How long to wait for writer thread termination + * + * We probably want a timeout here since we don't want to block shutdown indefinitely in case of + * any weirdness. + */ + const int THREAD_TERMINATION_TIMEOUT = 2000; + ~Manager(); void registerHandle(Interface* handle); void removeHandle(const QString& key); void loadSetting(Interface* handle); void saveSetting(Interface* handle); + + + /** + * @brief Force saving the config to disk. + * + * Normally unnecessary to use. Asynchronous. + */ void forceSave(); + /** + * @brief Write config to disk and terminate the writer thread + * + * This is part of the shutdown process. + */ + void terminateThread(); + signals: void valueChanged(const QString &key, const QVariant &value); void keyRemoved(const QString &key);