From 448f40be71dffa86a6581c3696627ccc1bdf74f2 Mon Sep 17 00:00:00 2001
From: Jordan Wiens <jordan@psifertex.com>
Date: Mon, 19 Feb 2024 15:04:00 -0500
Subject: 4.0 documentation

 - Refactored Type Documentation
 - Added Projects
 - Added Type Archives
 - Added New Sidebar Documentation
 - Added String Concepts
 - Added Light/Dark Mode
 - Added New Tab Documentation
 - Added BNIL Guide: HLIL docs
 - Added new cookbook examples
 - Added migration guide
 - Added script for building docsets
 - Added documentation for themes
 - Updated all images to Ninja Edit
 - API Docs : Documents BasicBlockEdge and BasicBlock
 - API Docs : Documents CoreVariable, Variable, and VariableNameAndType
 - API Docs : Corrects note on `BinaryView.update_analysis` and `BinaryView.update_analysis_and_wait` to represent that analysis is run by default for you now.
 - Many, many other changes
---
 python/variable.py | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

(limited to 'python/variable.py')

diff --git a/python/variable.py b/python/variable.py
index 0a86b850..75e95712 100644
--- a/python/variable.py
+++ b/python/variable.py
@@ -644,16 +644,28 @@ class StackVariableReference:
 
 @dataclass(frozen=True, order=True)
 class CoreVariable:
+	"""
+	``class CoreVariable`` is the base class for other variable types,
+	such as :py:meth:`VariableNameAndType` and :py:meth:`Variable`
+
+	:cvar index: Internal identifier
+	:cvar storage: If this variable is a stack variable
+		(`source_type == VariableSourceType.StackVariableSourceType`),
+		then the storage location is the offset onto the stack that contains
+		the first byte of this variable. Otherwise it's used as an internal identifier.
+	"""
 	_source_type: int
 	index: int
 	storage: int
 
 	@property
 	def identifier(self) -> int:
+		"""A UID for a variable within a function."""
 		return core.BNToVariableIdentifier(self.to_BNVariable())
 
 	@property
 	def source_type(self) -> VariableSourceType:
+		"""Whether this variable was created based off of an underlying register, stack location, or flag."""
 		return VariableSourceType(self._source_type)
 
 	def to_BNVariable(self):
@@ -675,6 +687,16 @@ class CoreVariable:
 
 @dataclass(frozen=True, order=True)
 class VariableNameAndType(CoreVariable):
+	"""
+	``class VariableNameAndType`` is a lightweight wrapper around a
+	variable and its name, useful for shuttling between APIs that require
+	them both. While :py:meth:`Variable` has :py:meth:`Variable.name` and
+	:py:meth:`Variable.type` fields, those require additional core calls
+	each time you fetch them.
+
+	:cvar name: The variable's name
+	:cvar type: The variable's type
+	"""
 	name: str
 	type: 'binaryninja.types.Type'
 
@@ -689,6 +711,10 @@ class VariableNameAndType(CoreVariable):
 
 
 class Variable(CoreVariable):
+	"""
+	``class Variable`` represents variables in Binary Ninja. Variables are resolved
+	in medium level IL, so variables objects are only valid for MLIL and above.
+	"""
 	def __init__(self, func: FunctionOrILFunction, source_type: VariableSourceType, index: int, storage: int):
 		super(Variable, self).__init__(int(source_type), index, storage)
 		if isinstance(func, binaryninja.function.Function):
@@ -759,10 +785,12 @@ class Variable(CoreVariable):
 
 	@property
 	def core_variable(self) -> CoreVariable:
+		"""Retrieve the underlying :py:meth:`CoreVariable` class"""
 		return CoreVariable(self._source_type, self.index, self.storage)
 
 	@property
 	def var_name_and_type(self) -> VariableNameAndType:
+		"""Convert to :py:meth:`VariableNameAndType` """
 		return VariableNameAndType.from_core_variable(self, self.name, self.type)
 
 	@property
@@ -794,7 +822,7 @@ class Variable(CoreVariable):
 
 	@property
 	def ssa_versions(self) -> Generator[int, None, None]:
-		"""Returns the SSA versions associated with this variable.  Doesn't return anything for aliased variables."""
+		"""Returns the SSA versions associated with this variable. Doesn't return anything for aliased variables."""
 		if self._il_function is None:
 			raise NotImplementedError("No IL function associated with variable")
 
@@ -825,6 +853,7 @@ class Variable(CoreVariable):
 
 	@property
 	def dead_store_elimination(self) -> DeadStoreElimination:
+		"""returns the dead store elimination setting for this variable"""
 		return DeadStoreElimination(
 		    core.BNGetFunctionVariableDeadStoreElimination(self._function.handle, self.to_BNVariable())
 		)
-- 
cgit v1.3.1