Add some documentation for Settings and BinaryView.

2 files changed, 67 insertions, 10 deletions

diff --git a/python/binaryview.py b/python/binaryview.py
index 7ff4d4cf..ee4a4fb3 100644
--- a/python/binaryview.py
+++ b/python/binaryview.py
@@ -639,12 +639,12 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)):
 	@classmethod
 	def get_view_of_file(cls, filename, update_analysis=True, progress_func=None):
 		"""
-		``get_view_of_file`` returns the first available, non-Raw `BinaryView` available.
+		``get_view_of_file`` opens and returns the first available `BinaryView`, excluding 'Raw' `BinaryViewType`s
 
-		:param str filename: Path to filename or bndb
-		:param bool update_analysis: defaults to True. Pass False to not run update_analysis_and_wait.
-		: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.
+		: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 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
 		"""
 		sqlite = b"SQLite format 3"
@@ -678,7 +678,33 @@ class BinaryViewType(with_metaclass(_BinaryViewTypeMetaclass, object)):
 		return bv
 
 	@classmethod
-	def get_view_of_file_with_options(cls, filename, update_analysis=True, options={}):
+	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
+
+		.. 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.
+
+		: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 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
+
+		:Example:
+
+			>>> BinaryViewType.get_view_of_file_with_options('/bin/ls', options={'loader.imageBase': 0xfffffff0000, 'loader.macho.processFunctionStarts' : False})
+			<BinaryView: '/bin/ls', start 0xfffffff0000, len 0xa290>
+			>>>
+		"""
+		isDatabase = filename.endswith(".bndb")
+		if isDatabase:
+			log.log_warn("Opening a database with options is not yet supported!")
+			return None
 		view = BinaryView.open(filename)
 		if view is None:
 			return None
@@ -1561,9 +1587,9 @@ class BinaryView(object):
 		performing incremental updates and is reset on a full function update. Per-function `update_count` tracks the
 		current number of incremental updates and is reset on a full function update. Per-function `submit_count` tracks the
 		current number of full updates that have completed.
-		
+
 		.. note:: `submit_count` is currently not reset across analysis updates.
-		
+
 		"""
 		info_ref = core.BNGetAnalysisInfo(self.handle)
 		info = info_ref[0]
diff --git a/python/settings.py b/python/settings.py
index 4521fa78..0c613fe1 100644
--- a/python/settings.py
+++ b/python/settings.py
@@ -30,6 +30,37 @@ from binaryninja.enums import SettingsScope
 
 
 class Settings(object):
+	"""
+	``class 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 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 \
+	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.
+
+	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.
+
+		=================== ============================ ============================== ===============================
+		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)
+		=================== ============================ ============================== ===============================
+
+	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.
+	"""
 	handle = core.BNCreateSettings("default")
 
 	def __init__(self, instance_id = "default", handle = None):
@@ -74,7 +105,7 @@ class Settings(object):
 
 	def register_group(self, group, title):
 		"""
-		``register_group`` registers a group for use with this Settings instance. Groups provide a simple way to organize settings.
+		``register_group`` registers a group in the schema for this `Settings` instance
 
 		:param str group: a unique identifier
 		:param str title: a user friendly name appropriate for UI presentation
@@ -90,7 +121,7 @@ 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 `Settings` instance
 
 		:param str key: a unique setting identifier in the form <group>.<name>
 		:param str properties: a JSON string describes the setting schema