Update documentation settings, update Settings documentation

1 files changed, 156 insertions, 0 deletions

diff --git a/binaryninjaapi.h b/binaryninjaapi.h
index ca28377a..522024e7 100644
--- a/binaryninjaapi.h
+++ b/binaryninjaapi.h
@@ -9490,6 +9490,94 @@ namespace BinaryNinja {
 		Ref<Repository> GetDefaultRepository();
 	};
 
+	/*! \c Settings provides a way to define and access settings in a hierarchical fashion. The value of a setting can
+		be defined for each hierarchical level, where each level overrides the preceding level. The backing-store for setting
+		values at each level is also configurable. This allows for ephemeral or platform-independent persistent settings storage
+		for components within Binary Ninja or consumers of the Binary Ninja API.
+
+		Each \c Settings instance has an \c instanceId which identifies a schema. The schema defines the settings contents
+		and the way in which settings are retrieved and manipulated. A new \c Settings instance defaults to using a value of <em><tt>default</tt></em>
+		for the \c instanceId . The <em><tt>default</tt></em> settings schema defines all of the settings available for the active Binary Ninja components
+		which include at a minimum, the settings defined by the Binary Ninja core. The <em><tt>default</tt></em> schema may additionally define settings
+		for the UI and/or installed plugins. Extending existing schemas, or defining new ones is accomplished by calling \c RegisterGroup()
+		and \c RegisterSetting() methods, or by deserializing an existing schema with \c DeserializeSchema() .
+
+		\note All settings in the <em><tt>default</tt></em> settings schema are rendered with UI elements in the Settings View of Binary Ninja UI.
+
+		Allowing setting overrides is an important feature and Binary Ninja accomplishes this by allowing one to override a setting at various
+		levels. The levels and their associated storage are shown in the following table. Default setting values are optional, and if specified,
+		saved in the schema itself.
+
+			================= ========================== ============== ==============================================
+			Setting Level     Settings Scope             Preference     Storage
+			================= ========================== ============== ==============================================
+			Default           SettingsDefaultScope       Lowest         Settings Schema
+			User              SettingsUserScope          -              <User Directory>/settings.json
+			Project           SettingsProjectScope       -              <Project Directory>/.binaryninja/settings.json
+			Resource          SettingsResourceScope      Highest        Raw BinaryView (Storage in BNDB)
+			================= ========================== ============== ==============================================
+
+		Settings are identified by a key, which is a string in the form of <b><tt><group>.<name></tt></b> or <b><tt><group>.<subGroup>.<name></tt></b> . Groups provide
+		a simple way to categorize settings. Sub-groups are optional and multiple sub-groups are allowed. When defining a settings group, the
+		\c RegisterGroup method allows for specifying a UI friendly title for use in the Binary Ninja UI. Defining a new setting requires a
+		unique setting key and a JSON string of property, value pairs. The following table describes the available properties and values.
+
+			==================   ======================================   ==================   ========   =======================================================================
+			Property             JSON Data Type                           Prerequisite         Optional   {Allowed Values} and Notes
+			==================   ======================================   ==================   ========   =======================================================================
+			"title"              string                                   None                 No         Concise Setting Title
+			"type"               string                                   None                 No         {"array", "boolean", "number", "string"}
+			"elementType"        string                                   "type" is "array"    No         {"string"}
+			"enum"               array : {string}                         "type" is "array"    Yes        Enumeration definitions
+			"enumDescriptions"   array : {string}                         "type" is "array"    Yes        Enumeration descriptions that match "enum" array
+			"minValue"           number                                   "type" is "number"   Yes        Specify 0 to infer unsigned (default is signed)
+			"maxValue"           number                                   "type" is "number"   Yes        Values less than or equal to INT_MAX result in a QSpinBox UI element
+			"precision"          number                                   "type" is "number"   Yes        Specify precision for a QDoubleSpinBox
+			"default"            {array, boolean, number, string, null}   None                 Yes        Specify optimal default value
+			"aliases"            array : {string}                         None                 Yes        Array of deprecated setting key(s)
+			"description"        string                                   None                 No         Detailed setting description
+			"ignore"             array : {string}                         None                 Yes        {"SettingsUserScope", "SettingsProjectScope", "SettingsResourceScope"}
+			"message"            string                                   None                 Yes        An optional message with additional emphasis
+			"readOnly"           bool                                     None                 Yes        Only enforced by UI elements
+			"optional"           bool                                     None                 Yes        Indicates setting can be null
+			"requiresRestart     bool                                     None                 Yes        Enable restart notification in the UI upon change
+			==================   ======================================   ==================   ========   =======================================================================
+
+		\note In order to facilitate deterministic analysis results, settings from the <em><tt>default</tt></em> schema that impact analysis are serialized
+		from Default, User, and Project scope into Resource scope during initial BinaryView analysis. This allows an analysis database to be opened
+		at a later time with the same settings, regardless if Default, User, or Project settings have been modified.
+
+		\note Settings that do not impact analysis (e.g. many UI settings) should use the \e "ignore" property to exclude
+			\e "SettingsProjectScope" and \e "SettingsResourceScope" from the applicable scopes for the setting.
+
+		<b>Example analysis plugin setting:</b>
+	 	\code{.cpp}
+		auto settings = Settings::Instance()
+
+	 	settings->RegisterGroup("myPlugin", "My Plugin")
+
+		settings->RegisterSetting("myPlugin.enablePreAnalysis",
+			R"~({
+			"title": "My Pre-Analysis Plugin",
+			"type": "boolean",
+			"default": false,
+			"description": "Enable extra analysis before core analysis.",
+			"ignore": ["SettingsProjectScope", "SettingsResourceScope"]
+			})~");
+
+	 	Json::Value options(Json::objectValue);
+		options["myPlugin.enablePreAnalysis"] = Json::Value(true);
+		Ref<BinaryView> bv = OpenView("/bin/ls", true, {}, options);
+
+		Settings::Instance()->Get<bool>("myPlugin.enablePreAnalysis"); // false
+	    Settings::Instance()->Get<bool>("myPlugin.enablePreAnalysis", bv); // true
+		\endcode
+
+	 	<b>Getting a settings value:</b>
+	 	\code{.cpp}
+	    bool excludeUnreferencedStrings = Settings::Instance()->Get<bool>("ui.stringView.excludeUnreferencedStrings", bv);
+	    \endcode
+	 */
 	class Settings : public CoreRefCountObject<BNSettings, BNNewSettingsReference, BNFreeSettings>
 	{
 		std::string m_instanceId;
@@ -9502,12 +9590,51 @@ namespace BinaryNinja {
 		static Ref<Settings> Instance(const std::string& schemaId = "");
 		virtual ~Settings() {}
 
+		/*! Sets the resource identifier for this \c Settings instance. When accessing setting values at the
+			\c SettingsResourceScope level, the resource identifier is passed along through the backing store interface.
+
+			\note Currently the only available backing store for \c SettingsResourceScope is a \c BinaryView object. In the context
+			of a \c BinaryView the resource identifier is the \c BinaryViewType name. All settings for this type of backing store
+			are saved in the \e 'Raw' \c BinaryViewType . This enables the configuration of setting values such that they are available
+			during \c BinaryView creation and initialization.
+
+			\param resourceId a unique identifier
+		 */
 		void SetResourceId(const std::string& resourceId = "");
 
+		/*! Registers a group in the schema for this \c Settings instance
+			
+			\param group a unique identifier
+			\param title a user friendly name appropriate for UI presentation
+			\return True on success, False on failure
+		 */
 		bool RegisterGroup(const std::string& group, const std::string& title);
+		
+		/*! Registers a new setting with this \c Settings instance
+			
+			\param key a unique setting identifier in the form <b>'<group>.<name>'</b>
+			\param properties a JSON string describes the setting schema
+			\return True on success, False on failure.
+		 */
 		bool RegisterSetting(const std::string& key, const std::string& properties);
+		
+		/*! Determine if a setting identifier exists in the active settings schema
+			
+			\param key the setting identifier
+			\return True if the identifier exists in this active settings schema, False otherwise
+		 */
 		bool Contains(const std::string& key);
+		
+		/*! Determine if the active settings schema is empty
+			
+			\return True if the active settings schema is empty, False otherwise
+		 */
 		bool IsEmpty();
+		
+		/*! Retrieve the list of setting identifiers in the active settings schema
+			
+			\return List of setting identifiers
+		 */
 		std::vector<std::string> Keys();
 
 		template <typename T>
@@ -9533,8 +9660,33 @@ namespace BinaryNinja {
 		bool ResetAll(
 		    Ref<BinaryView> view = nullptr, BNSettingsScope scope = SettingsAutoScope, bool schemaOnly = true);
 
+		/*! Get the current setting value for a particular key
+			
+			\code{.cpp}
+		 	bool excludeUnreferencedStrings = Settings::Instance()->Get<bool>("ui.stringView.excludeUnreferencedStrings", data);
+			\endcode
+			
+			\tparam T type for the value you are retrieving
+			\param key Key for the setting
+			\param view BinaryView, for factoring in resource-scoped settings
+			\param scope Scope for the settings
+			\return Value for the setting, with type T
+		 */
 		template <typename T>
 		T Get(const std::string& key, Ref<BinaryView> view = nullptr, BNSettingsScope* scope = nullptr);
+		
+		/*! Get the current settings value for a particular key, as a JSON representation of its value.
+			
+			\code{.cpp}
+		    string value = Settings::Instance()->GetJson("analysis.mode");
+			// '"full"'
+		 	\endcode
+			
+			\param key Key for the setting
+			\param view BinaryView, for factoring in resource-scoped settings
+			\param scope Scope for the settings
+			\return JSON value for the setting, as a string
+		 */
 		std::string GetJson(const std::string& key, Ref<BinaryView> view = nullptr, BNSettingsScope* scope = nullptr);
 
 		bool Set(const std::string& key, bool value, Ref<BinaryView> view = nullptr,
@@ -9558,6 +9710,9 @@ namespace BinaryNinja {
 	};
 
 	// explicit specializations
+	/*! \cond DOXYGEN_HIDE
+		Prevent these from having docs autogenerated twice, due to an odd quirk with doxygen
+	*/
 	template <>
 	std::vector<std::string> Settings::QueryProperty<std::vector<std::string>>(
 	    const std::string& key, const std::string& property);
@@ -9574,6 +9729,7 @@ namespace BinaryNinja {
 	template <>
 	std::vector<std::string> Settings::Get<std::vector<std::string>>(
 	    const std::string& key, Ref<BinaryView> view, BNSettingsScope* scope);
+	/*! \endcond */
 
 	typedef BNMetadataType MetadataType;