Clean-up BinaryView and Settings documentation.

2 files changed, 89 insertions, 37 deletions

diff --git a/python/binaryview.py b/python/binaryview.py
index 7e7e323b..5a1741c5 100644
--- a/python/binaryview.py
+++ b/python/binaryview.py
@@ -639,13 +639,13 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)):
 	@classmethod
 	def get_view_of_file(cls, filename, update_analysis=True, progress_func=None):
 		"""
-		``get_view_of_file`` opens and returns the first available `BinaryView`, excluding 'Raw' `BinaryViewType`s
+		``get_view_of_file`` opens and returns the first available :class:`BinaryView`, excluding *'Raw'* :class:`BinaryViewType`s
 
 		:param str filename: path to filename or bndb to open
-		:param bool update_analysis: whether or not to run `update_analysis_and_wait` after opening a `BinaryView`, defaults to True
+		:param bool update_analysis: whether or not to run :func:`update_analysis_and_wait` after opening a :class:`BinaryView`, defaults to ``True``
 		:param callback progress_func: optional function to be called with the current progress and total count
-		:return: returns a BinaryView object for the given filename
-		:rtype: BinaryView or None
+		:return: returns a :class:`BinaryView` object for the given filename
+		:rtype: :class:`BinaryView` or ``None``
 		"""
 		sqlite = b"SQLite format 3"
 		isDatabase = filename.endswith(".bndb")
@@ -681,19 +681,19 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)):
 	def get_view_of_file_with_options(cls, filename, update_analysis=True, progress_func=None, options={}):
 		"""
 		``get_view_of_file_with_options`` opens, generates default load options (which are overridable), and returns the first available \
-		`BinaryView`, excluding 'Raw' `BinaryViewType`s
+		:class:`BinaryView`, excluding *'Raw'* :class:`BinaryViewType`s
 
-		.. note:: Calling this method without providing options is not necessarily equivalent to simply calling `get_view_of_file`. Since \
-		`BinaryViewType`s are in control of generating load options, this method allows an alternative default way to open a file. For \
-		example, opening a relocatable object file with `get_view_of_file` sets 'loader.imageBase' to 0, whereas opening with `get_view_of_file_with_options` \
-		sets 'loader.imageBase' to 0x400000 for 64-bit binaries, or 0x10000 for 32-bit binaries, by default.
+		.. note:: Calling this method without providing options is not necessarily equivalent to simply calling :func:`get_view_of_file`. Since \
+		:class:`BinaryViewType`s are in control of generating load options, this method allows an alternative default way to open a file. For \
+		example, opening a relocatable object file with :func:`get_view_of_file` sets **'loader.imageBase'** to 0, whereas opening with \
+		:func:`get_view_of_file_with_options` sets **'loader.imageBase'** to ``0x400000`` for 64-bit binaries, or ``0x10000`` for 32-bit binaries, by default.
 
 		:param str filename: path to filename or bndb to open
-		:param bool update_analysis: whether or not to run `update_analysis_and_wait` after opening a `BinaryView`, defaults to True
+		:param bool update_analysis: whether or not to run :func:`update_analysis_and_wait` after opening a :class:`BinaryView`, defaults to ``True``
 		:param callback progress_func: optional function to be called with the current progress and total count
 		:param dict options: a dictionary in the form {str : str}, where key is a setting identifier, and value is a JSON formatted str
-		:return: returns a BinaryView object for the given filename
-		:rtype: BinaryView or None
+		:return: returns a :class:`BinaryView` object for the given filename
+		:rtype: :class:`BinaryView` or ``None``
 
 		:Example:
 
@@ -5122,6 +5122,13 @@ class BinaryView(object):
 		core.BNBinaryViewRemoveMetadata(self.handle, key)
 
 	def get_load_settings_type_names(self):
+		"""
+		``get_load_settings_type_names`` retrieve a list :class:`BinaryViewType` names for which load settings exist in \
+		this :class:`BinaryView` context
+
+		:return: list of :class:`BinaryViewType` names
+		:rtype: list(str)
+		"""
 		result = []
 		count = ctypes.c_ulonglong(0)
 		names = core.BNBinaryViewGetLoadSettingsTypeNames(self.handle, count)
@@ -5131,12 +5138,26 @@ class BinaryView(object):
 		return result
 
 	def get_load_settings(self, type_name):
+		"""
+		``get_load_settings`` retrieve a :class:`Settings` object which defines the load settings for the given :class:`BinaryViewType` ``type_name``
+
+		:param str type_name: the :class:`BinaryViewType` name
+		:return: the load settings
+		:rtype: :class:`Settings`, or ``None``
+		"""
 		settings_handle = core.BNBinaryViewGetLoadSettings(self.handle, type_name)
 		if settings_handle is None:
 			return None
 		return settings.Settings(handle=settings_handle)
 
 	def set_load_settings(self, type_name, settings):
+		"""
+		``set_load_settings`` set a :class:`Settings` object which defines the load settings for the given :class:`BinaryViewType` ``type_name``
+
+		:param str type_name: the :class:`BinaryViewType` name
+		:param Settings settings: the load settings
+		:rtype: None
+		"""
 		core.BNBinaryViewSetLoadSettings(self.handle, type_name, settings.handle)
 
 	def __setattr__(self, name, value):
@@ -5155,11 +5176,11 @@ class BinaryView(object):
 			- Symbols are everything in ``bv.symbols``, unnamed DataVariables (i.e. ``data_00005000``), unnamed functions (i.e. ``sub_00005000``), or section names (i.e. ``.text``)
 			- Numbers are defaulted to hexadecimal thus `_printf + 10` is equivalent to `printf + 0x10` If decimal numbers required use the decimal prefix.
 			- Since numbers and symbols can be ambiguous its recommended that you prefix your numbers with the following:
-			
+
 				- ``0x`` - Hexadecimal
 				- ``0n`` - Decimal
 				- ``0`` - Octal
-			
+
 			- In the case of an ambiguous number/symbol (one with no prefix) for instance ``12345`` we will first attempt
 			  to look up the string as a symbol, if a symbol is found its address is used, otherwise we attempt to convert
 			  it to a hexadecimal number.
@@ -5171,7 +5192,7 @@ class BinaryView(object):
 				- ``[<expression>].w`` - read the word (2 bytes) at ``<expression>``
 				- ``[<expression>].d`` - read the dword (4 bytes) at ``<expression>``
 				- ``[<expression>].q`` - read the quadword (8 bytes) at ``<expression>``
-			
+
 			- The ``$here`` keyword can be used in calculations and is defined as the ``here`` parameter
 			- The ``$start``/``$end`` keyword represents the address of the first/last bytes in the file respectively
 
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 = []