Clean-up BinaryView and Settings documentation.

1 files changed, 53 insertions, 22 deletions

diff --git a/python/settings.py b/python/settings.py
index 0c613fe1..fec4023d 100644
--- a/python/settings.py
+++ b/python/settings.py
@@ -36,30 +36,30 @@ class Settings(object):
 	values is also configurable and can be different for each level. This allows for ephemeral or platform-independent \
 	persistent settings storage for components within Binary Ninja or consumers of the Binary Ninja API.
 
-	Each `Settings` instance has a unique `instance_id` and a settings schema which defines the contents for the settings \
-	repository. By default, a new `Settings` instance contains an empty schema. A schema can be built up by using the \
-	`register_group` and `register_setting` methods, or by deserializing an existing schema with `deserialize_schema` \
-	Binary Ninja provides a default `Settings` instance identified as 'default'. The 'default' settings repository defines \
+	Each :class:`Settings` instance has a unique ``instance_id`` and a settings schema that define the contents for the settings \
+	repository. By default, a new :class:`Settings` instance contains an empty schema. A schema can be built up by using the \
+	:func:`register_group` and func:`register_setting` methods, or by deserializing an existing schema with :func:`deserialize_schema`. \
+	Binary Ninja provides a default :class:`Settings` instance identified as *'default'*. The *'default'* settings repository defines \
 	all of the settings available for the active Binary Ninja components.
 
 	.. note:: The Binary Ninja Application provides many settings that are only applicable to the UI, and thus would not be \
-	defined in the 'default' settings schema for Binary Ninja headless.
+	defined in the *'default'* settings schema for Binary Ninja headless.
 
-	Except for default setting values, values are stored separately from the schema in a backing store. The backing store can \
-	be different for each level. When accessing setting values, the order of precedence is: Context > Workspace > User > Default.
+	Except for *default* setting values, setting values are optional for other levels and stored separately from the schema in a \
+	backing store. The backing store can be different for each level. When querying setting values, the values returned or modified \
+	are in order of preference (i.e. ``SettingsAutoScope``). It is possible to override the scope by specifying the desired ``SettingsScope``.
 
-		=================== ============================ ============================== ===============================
-		Setting Level       Settings Scope               Backing Store ('default')        Backing Store (Other)
-		=================== ============================ ============================== ===============================
-		Default             SettingsDefaultScope         Settings Schema                  Settings Schema
-		User                SettingsUserScope            <User Directory>/settings.json   <TBD>
-		Workspace           SettingsWorkspaceScope       <TBD>                            <TBD>
-		Context             SettingsContextScope         BinaryView (Storage in bndb)    BinaryView (Storage in bndb)
-		=================== ============================ ============================== ===============================
+		================= ========================== ============== ================================ ===============================
+		Setting Level     Settings Scope             Preference     Backing Store ('default')        Backing Store (Other)
+		================= ========================== ============== ================================ ===============================
+		Default           SettingsDefaultScope       Lowest         Settings Schema                  Settings Schema
+		User              SettingsUserScope          -              <User Directory>/settings.json   <TBD>
+		Workspace         SettingsWorkspaceScope     -              <TBD>                            <TBD>
+		Context           SettingsContextScope       Highest        BinaryView (Storage in bndb)     BinaryView (Storage in bndb)
+		================= ========================== ============== ================================ ===============================
 
-	Individual settings are identified by a key, which is a string in the form of '<group>.<name>'. Groups provide a simple way \
-	to categorize settings. Additionally, sub-categories can be expressed directly in the name part of the key with the same dot \
-	notation.
+	Individual settings are identified by a key, which is a string in the form of **'<group>.<name>'**. Groups provide a simple way \
+	to categorize settings. Additionally, sub-categories can be expressed directly in the name part of the key with a similar dot notation.
 	"""
 	handle = core.BNCreateSettings("default")
 
@@ -95,17 +95,29 @@ class Settings(object):
 
 	@property
 	def instance_id(self):
-		"""(read-only)"""
+		"""Returns the ``instance_id`` for this :class:`Settings` repository (read-only)"""
 		return self._instance_id
 
 	def set_resource_id(self, resource_id = None):
+		"""
+		``set_resource_id`` Sets the resource identifier for this class:`Settings` instance. When accessing setting values at the \
+		``SettingsContextScope`` level, the resource identifier is passed along through the backing store interface.
+
+		.. note:: Currently the only available backing store for ``SettingsContextScope`` is a :class:`BinaryView` object. In the context \
+		of a :class:`BinaryView` the resource identifier is the :class:`BinaryViewType` name. All settings for this type of backing store \
+		are saved in the *'Raw'* :class:`BinaryViewType`. This enables the configuration of setting values such that they are available \
+		during :class:`BinaryView` creation and initialization.
+
+		:param str resource_id: a unique identifier
+		:rtype: None
+		"""
 		if resource_id is None:
 			resource_id = ""
 		core.BNSettingsSetResourceId(self.handle, resource_id)
 
 	def register_group(self, group, title):
 		"""
-		``register_group`` registers a group in the schema for this `Settings` instance
+		``register_group`` registers a group in the schema for this :class:`Settings` instance
 
 		:param str group: a unique identifier
 		:param str title: a user friendly name appropriate for UI presentation
@@ -121,9 +133,9 @@ class Settings(object):
 
 	def register_setting(self, key, properties):
 		"""
-		``register_setting`` registers a new setting with this `Settings` instance
+		``register_setting`` registers a new setting with this :class:`Settings` instance
 
-		:param str key: a unique setting identifier in the form <group>.<name>
+		:param str key: a unique setting identifier in the form **'<group>.<name>'**
 		:param str properties: a JSON string describes the setting schema
 		:return: True on success, False on failure.
 		:rtype: bool
@@ -137,12 +149,31 @@ class Settings(object):
 		return core.BNSettingsRegisterSetting(self.handle, key, properties)
 
 	def contains(self, key):
+		"""
+		``contains`` determine if a setting identifier exists in the active settings schema
+
+		:param str key: the setting identifier
+		:return: True if the identifier exists in this active settings schema, False otherwise
+		:rtype: bool
+		"""
 		return core.BNSettingsContains(self.handle, key)
 
 	def is_empty(self):
+		"""
+		``is_empty`` determine if the active settings schema is empty
+
+		:return: True if the active settings schema is empty, False otherwise
+		:rtype: bool
+		"""
 		return core.BNSettingsIsEmpty(self.handle)
 
 	def keys(self):
+		"""
+		``keys`` retrieve the list of setting identifiers in the active settings schema
+
+		:return: list of setting identifiers
+		:rtype: list(str)
+		"""
 		length = ctypes.c_ulonglong()
 		result = core.BNSettingsKeysList(self.handle, ctypes.byref(length))
 		out_list = []