settings: Document BasicSetting, add Ranged

src/common/settings_common.h

@@ -57,6 +57,10 @@ public:
     u32 count;
 };
 
+/**
+ * BasicSetting is an abstract class that only keeps track of metadata. The string methods are
+ * available to get data values out.
+ */
 class BasicSetting {
 protected:
     explicit BasicSetting(Linkage& linkage, const std::string& name, enum Category category_,
@@ -65,45 +69,117 @@ protected:
 public:
     virtual ~BasicSetting();
 
-    /* Data retrieval */
+    /*
+     * Data retrieval
+     */
 
+    /**
+     * Returns a string representation of the internal data. If the Setting is Switchable, it
+     * respects the internal global state: it is based on GetValue().
+     *
+     * @returns A string representation of the internal data.
+     */
     [[nodiscard]] virtual std::string ToString() const = 0;
+
+    /**
+     * Returns a string representation of the global version of internal data. If the Setting is
+     * not Switchable, it behaves like ToString.
+     *
+     * @returns A string representation of the global version of internal data.
+     */
     [[nodiscard]] virtual std::string ToStringGlobal() const;
+
+    /**
+     * @returns A string representation of the Setting's default value.
+     */
     [[nodiscard]] virtual std::string DefaultToString() const = 0;
+
+    /**
+     * Returns a string representation of the minimum value of the setting. If the Setting is not
+     * ranged, the string represents the default initialization of the data type.
+     *
+     * @returns A string representation of the minimum value of the setting.
+     */
     [[nodiscard]] virtual std::string MinVal() const = 0;
+
+    /**
+     * Returns a string representation of the maximum value of the setting. If the Setting is not
+     * ranged, the string represents the default initialization of the data type.
+     *
+     * @returns A string representation of the maximum value of the setting.
+     */
     [[nodiscard]] virtual std::string MaxVal() const = 0;
+
+    /**
+     * Takes a string input, converts it to the internal data type if necessary, and then runs
+     * SetValue with it.
+     *
+     * @param load String of the input data.
+     */
     virtual void LoadString(const std::string& load) = 0;
+
+    /**
+     * Returns a string representation of the data. If the data is an enum, it returns a string of
+     * the enum value. If the internal data type is not an enum, this is equivalent to ToString.
+     *
+     * e.g. renderer_backend.Canonicalize() == "OpenGL"
+     *
+     * @returns Canonicalized string representation of the internal data
+     */
     [[nodiscard]] virtual std::string Canonicalize() const = 0;
 
-    /* Identification */
+    /*
+     * Metadata
+     */
 
-    [[nodiscard]] virtual std::type_index TypeId() const = 0;
-    [[nodiscard]] virtual constexpr bool IsEnum() const = 0;
     /**
-     * Returns whether the current setting is Switchable.
+     * @returns A unique identifier for the Setting's internal data type.
+     */
+    [[nodiscard]] virtual std::type_index TypeId() const = 0;
+
+    /**
+     * Returns true if the Setting's internal data type is an enum.
+     *
+     * @returns True if the Setting's internal data type is an enum
+     */
+    [[nodiscard]] virtual constexpr bool IsEnum() const = 0;
+
+    /**
+     * Returns true if the current setting is Switchable.
      *
      * @returns If the setting is a SwitchableSetting
      */
     [[nodiscard]] virtual constexpr bool Switchable() const {
         return false;
     }
+
     /**
-     * Returns the save preference of the setting i.e. when saving or reading the setting from a
+     * Returns true to suggest that a frontend can read or write the setting to a configuration
-     * frontend, whether this setting should be skipped.
+     * file.
      *
      * @returns The save preference
      */
     [[nodiscard]] bool Save() const;
+
+    /**
+     * @returns true if the current setting can be changed while the guest is running.
+     */
     [[nodiscard]] bool RuntimeModfiable() const;
+
+    /**
+     * @returns A unique number corresponding to the setting.
+     */
     [[nodiscard]] constexpr u32 Id() const {
         return id;
     }
+
     /**
      * Returns the setting's category AKA INI group.
      *
      * @returns The setting's category
      */
     [[nodiscard]] Category Category() const;
+
     /**
      * Returns the label this setting was created with.
      *
@@ -111,17 +187,38 @@ public:
      */
     [[nodiscard]] const std::string& GetLabel() const;
 
-    /* Switchable settings */
+    /**
+     * @returns If the Setting checks input values for valid ranges.
+     */
+    [[nodiscard]] virtual constexpr bool Ranged() const = 0;
 
+    /*
+     * Switchable settings
+     */
+
+    /**
+     * Sets a setting's global state. True means use the normal setting, false to use a custom
+     * value. Has no effect if the Setting is not Switchable.
+     *
+     * @param global The desired state
+     */
     virtual void SetGlobal(bool global);
+
+    /**
+     * Returns true if the setting is using the normal setting value. Always true if the setting is
+     * not Switchable.
+     *
+     * @returns The Setting's global state
+     */
     [[nodiscard]] virtual bool UsingGlobal() const;
 
 private:
     const std::string label;      ///< The setting's label
     const enum Category category; ///< The setting's category AKA INI group
-    const u32 id;
+    const u32 id;                 ///< Unique integer for the setting
-    const bool save;
+    const bool save; ///< Suggests if the setting should be saved and read to a frontend config
-    const bool runtime_modifiable;
+    const bool
+        runtime_modifiable; ///< Suggests if the setting can be modified while a guest is running
 };
 
 } // namespace Settings

src/common/settings_setting.h

@@ -198,6 +198,10 @@ public:
         return this->ToString(maximum);
     }
 
+    constexpr bool Ranged() const override {
+        return ranged;
+    }
+
 protected:
     Type value{};               ///< The setting
     const Type default_value{}; ///< The default value