add additional documentation warning users from creating objects with handles directly

6 files changed, 32 insertions, 2 deletions

diff --git a/python/basicblock.py b/python/basicblock.py
index 24f549d7..208ab9e7 100644
--- a/python/basicblock.py
+++ b/python/basicblock.py
@@ -49,6 +49,9 @@ class BasicBlockEdge:
 
 
 class BasicBlock:
+	"""
+	The ``BasicBlock`` object is returned during analysis and should not be directly instantiated.
+	"""
 	def __init__(self, handle: core.BNBasicBlockHandle, view: Optional['binaryview.BinaryView'] = None):
 		self._view = view
 		_handle = core.BNBasicBlockHandle
diff --git a/python/binaryview.py b/python/binaryview.py
index 37d85580..b2df6ca2 100644
--- a/python/binaryview.py
+++ b/python/binaryview.py
@@ -681,8 +681,11 @@ class _BinaryViewTypeMetaclass(type):
 
 
 class BinaryViewType(metaclass=_BinaryViewTypeMetaclass):
-	# Used to force Python callback objects to not get garbage collected
-	_platform_recognizers = {}
+	"""
+	The ``BinaryViewType`` object is used internally and should not be directly instantiated.
+	"""
+
+	_platform_recognizers = {} # Used to force Python callback objects to not get garbage collected
 
 	def __init__(self, handle: core.BNBinaryViewTypeHandle):
 		_handle = core.BNBinaryViewTypeHandle
@@ -1096,6 +1099,9 @@ class BinaryViewType(metaclass=_BinaryViewTypeMetaclass):
 
 
 class Segment:
+	"""
+	The ``Segment`` object is returned during BinaryView creation and should not be directly instantiated.
+	"""
 	def __init__(self, handle: core.BNSegmentHandle):
 		self.handle = handle
 
@@ -1193,6 +1199,9 @@ class Segment:
 
 
 class Section:
+	"""
+	The ``Section`` object is returned during BinaryView creation and should not be directly instantiated.
+	"""
 	def __init__(self, handle: core.BNSectionHandle):
 		self.handle = handle
 
@@ -1272,6 +1281,9 @@ class Section:
 
 
 class TagType:
+	"""
+	The ``TagType`` object is created by the create_tag_type API and should not be directly instantiated.
+	"""
 	def __init__(self, handle: core.BNTagTypeHandle):
 		self.handle = handle
 
@@ -1338,6 +1350,9 @@ class TagType:
 
 
 class Tag:
+	"""
+	The ``Tag`` object is created by other APIs (create_*_tag) and should not be directly instantiated.
+	"""
 	def __init__(self, handle: core.BNTagHandle):
 		self.handle = handle
 
diff --git a/python/highlevelil.py b/python/highlevelil.py
index 176b2994..c77a4e39 100644
--- a/python/highlevelil.py
+++ b/python/highlevelil.py
@@ -2527,6 +2527,9 @@ class HighLevelILFunction:
 
 
 class HighLevelILBasicBlock(basicblock.BasicBlock):
+	"""
+	The ``HighLevelILBasicBlock`` object is returned during analysis and should not be directly instantiated.
+	"""
 	def __init__(
 	    self, handle: core.BNBasicBlockHandle, owner: HighLevelILFunction, view: Optional['binaryview.BinaryView']
 	):
diff --git a/python/lowlevelil.py b/python/lowlevelil.py
index 22ea1e64..faba03fe 100644
--- a/python/lowlevelil.py
+++ b/python/lowlevelil.py
@@ -4699,6 +4699,9 @@ class LowLevelILFunction:
 
 
 class LowLevelILBasicBlock(basicblock.BasicBlock):
+	"""
+	The ``LogLevelILBasicBlock`` object is returned during analysis and should not be directly instantiated.
+	"""
 	def __init__(
 	    self, handle: core.BNBasicBlockHandle, owner: LowLevelILFunction, view: Optional['binaryview.BinaryView']
 	):
diff --git a/python/mediumlevelil.py b/python/mediumlevelil.py
index 26610733..f40a4b21 100644
--- a/python/mediumlevelil.py
+++ b/python/mediumlevelil.py
@@ -3196,6 +3196,9 @@ class MediumLevelILFunction:
 
 
 class MediumLevelILBasicBlock(basicblock.BasicBlock):
+	"""
+	The ``MediumLevelILBasicBlock`` object is returned during analysis and should not be directly instantiated.
+	"""
 	def __init__(
 	    self, handle: core.BNBasicBlockHandle, owner: MediumLevelILFunction,
 	    view: Optional['binaryview.BinaryView'] = None
diff --git a/python/types.py b/python/types.py
index b086ef78..62cc0154 100644
--- a/python/types.py
+++ b/python/types.py
@@ -476,6 +476,9 @@ class MutableTypeBuilder:
 
 
 class TypeBuilder:
+	"""
+	All TypeBuilder objects should not be instantiated directly but created via ``.create`` APIs.
+	"""
 	def __init__(
 	    self, handle: core.BNTypeBuilderHandle, platform: '_platform.Platform' = None,
 	    confidence: int = core.max_confidence