Add documentation to the constant renderer and string recognizer APIs

Author: D0ntPanic

binaryninjaapi.h

@@ -5372,6 +5372,11 @@ namespace BinaryNinja {
 		std::vector<TypeReferenceSource> typeRefs;
 	};
 
+	/*! Represents a custom string type. String types contain the name of the string type and the prefix
+		and postfix used to render them in code.
+
+		\ingroup stringrecognizer
+	*/
 	class CustomStringType: public StaticCoreRefCountObject<BNCustomStringType>
 	{
 	public:
@@ -5384,6 +5389,10 @@ namespace BinaryNinja {
 			const std::string& name, const std::string& stringPrefix = "", const std::string& stringPostfix = "");
 	};
 
+	/*! Location associated with a derived string. Locations are optional.
+
+		\ingroup stringrecognizer
+	*/
 	struct DerivedStringLocation
 	{
 		BNDerivedStringLocationType locationType;
@@ -5418,6 +5427,12 @@ namespace BinaryNinja {
 		}
 	};
 
+	/*! Contains a string derived from code or data. The string does not need to be directly present in
+		the binary in its raw form. Derived strings can have optional locations to data or code. When
+		creating new derived strings, a custom type should be registered with \c CustomStringType::register.
+
+		\ingroup stringrecognizer
+	*/
 	struct DerivedString
 	{
 		StringRef value;
@@ -21425,6 +21440,10 @@ namespace BinaryNinja {
 		) override;
 	};
 
+	/*! \c ConstantRenderer allows custom rendering of constants in high level representations.
+
+		\ingroup constantrenderer
+	*/
 	class ConstantRenderer : public StaticCoreRefCountObject<BNConstantRenderer>
 	{
 		std::string m_nameForRegister;
@@ -21435,9 +21454,47 @@ namespace BinaryNinja {
 
 		std::string GetName() const;
 
+		/*! Determines if the rendering methods should be called for the given expression type. It is optional
+			to override this method. If the method isn't overridden, all expression types are passed to the
+			rendering methods.
+
+		    \param func \c HighLevelILFunction representing the high level function to be queried
+		    \param type Type of the expression
+		    \return \c true if the constant should be passed to the rendering methods, \c false otherwise
+		*/
 		virtual bool IsValidForType(HighLevelILFunction* func, Type* type);
+
+		/*! Can be overridden to render a constant that is not a pointer. The expression type and value of the
+			expression are given. If the expression is not handled by this constant renderer, this method should
+			return \c false
+
+			To render a constant, emit the tokens to the tokens object and return \c true
+
+		    \param instr High level expression
+		    \param type Type of the expression
+		    \param val Value of the expression
+			\param tokens Token emitter for adding the rendered tokens
+			\param settings Settings for rendering
+			\param precedence Operator precedence of the expression
+			\return \c true if the constant was rendered, \c false otherwise
+		*/
 		virtual bool RenderConstant(const HighLevelILInstruction& instr, Type* type, int64_t val,
 			HighLevelILTokenEmitter& tokens, DisassemblySettings* settings, BNOperatorPrecedence precedence);
+
+		/*! Can be overridden to render a constant pointer. The expression type and value of the
+			expression are given. If the expression is not handled by this constant renderer, this method should
+			return \c false
+
+			To render a constant, emit the tokens to the tokens object and return \c true
+
+		    \param instr High level expression
+		    \param type Type of the expression
+		    \param val Value of the expression
+			\param tokens Token emitter for adding the rendered tokens
+			\param settings Settings for rendering
+			\param precedence Operator precedence of the expression
+			\return \c true if the constant was rendered, \c false otherwise
+		*/
 		virtual bool RenderConstantPointer(const HighLevelILInstruction& instr, Type* type, int64_t val,
 			HighLevelILTokenEmitter& tokens, DisassemblySettings* settings, BNSymbolDisplayType symbolDisplay,
 			BNOperatorPrecedence precedence);
@@ -21473,6 +21530,10 @@ namespace BinaryNinja {
 			BNOperatorPrecedence precedence) override;
 	};
 
+	/*! \c StringRecognizer recognizes custom strings found in high level expressions.
+
+		\ingroup stringrecognizer
+	*/
 	class StringRecognizer : public StaticCoreRefCountObject<BNStringRecognizer>
 	{
 		std::string m_nameForRegister;
@@ -21483,13 +21544,70 @@ namespace BinaryNinja {
 
 		std::string GetName() const;
 
+		/*! Determines if the string recognizer should be called for the given expression type. It is optional
+			to override this method. If the method isn't overridden, all expression types are passed to the
+			string recognizer.
+
+		    \param func \c HighLevelILFunction representing the high level function to be queried
+		    \param type Type of the expression
+		    \return \c true if the expression should be passed to the string recognizer, \c false otherwise
+		*/
 		virtual bool IsValidForType(HighLevelILFunction* func, Type* type);
+
+		/*! Can be overridden to recognize strings for a constant that is not a pointer. The expression type and
+			value of the expression are given. If no string is found for this expression, this method should
+			return \c std::nullopt
+
+			If a string is found, return a \c DerivedString with the string information.
+
+		    \param instr High level expression
+		    \param type Type of the expression
+		    \param val Value of the expression
+		    \return Optional \c DerivedString for any string that is found
+		*/
 		virtual std::optional<DerivedString> RecognizeConstant(
 			const HighLevelILInstruction& instr, Type* type, int64_t val);
+
+		/*! Can be overridden to recognize strings for a constant pointer. The expression type and
+			value of the expression are given. If no string is found for this expression, this method should
+			return \c std::nullopt
+
+			If a string is found, return a \c DerivedString with the string information.
+
+		    \param instr High level expression
+		    \param type Type of the expression
+		    \param val Value of the expression
+		    \return Optional \c DerivedString for any string that is found
+		*/
 		virtual std::optional<DerivedString> RecognizeConstantPointer(
 			const HighLevelILInstruction& instr, Type* type, int64_t val);
+
+		/*! Can be overridden to recognize strings for an external symbol. The expression type and
+			value of the expression are given. If no string is found for this expression, this method should
+			return \c std::nullopt
+
+			If a string is found, return a \c DerivedString with the string information.
+
+		    \param instr High level expression
+		    \param type Type of the expression
+		    \param val Value of the expression
+			\param offset Offset into the external symbol
+		    \return Optional \c DerivedString for any string that is found
+		*/
 		virtual std::optional<DerivedString> RecognizeExternPointer(
 			const HighLevelILInstruction& instr, Type* type, int64_t val, uint64_t offset);
+
+		/*! Can be overridden to recognize strings for an imported symbol. The expression type and
+			value of the expression are given. If no string is found for this expression, this method should
+			return \c std::nullopt
+
+			If a string is found, return a \c DerivedString with the string information.
+
+		    \param instr High level expression
+		    \param type Type of the expression
+		    \param val Value of the expression
+		    \return Optional \c DerivedString for any string that is found
+		*/
 		virtual std::optional<DerivedString> RecognizeImport(
 			const HighLevelILInstruction& instr, Type* type, int64_t val);
 

python/binaryview.py

@@ -528,6 +528,8 @@ def view(self) -> 'BinaryView':
 
 
 class StringRef:
+	"""Deduplicated reference to a string owned by the Binary Ninja core. Use `str` or `bytes` to convert
+	this to a standard Python string or sequence of bytes."""
 	def __init__(self, handle):
 		self.handle = core.handle_of_type(handle, core.BNStringRef)
 
@@ -589,13 +591,20 @@ def __hash__(self):
 
 @dataclass(frozen=True)
 class DerivedStringLocation:
+	"""Location associated with a derived string. Locations are optional."""
 	location_type: 'DerivedStringLocationType'
 	address: int
 	length: int
 
 
 @dataclass(frozen=True)
 class DerivedString:
+	"""
+	Contains a string derived from code or data. The string does not need to be directly present in
+	the binary in its raw form. Derived strings can have optional locations to data or code. When
+	creating new derived strings, a custom type should be registered with
+	:py:func:`~binaryninja.stringrecognizer.CustomStringType.register` on :py:class:`~binaryninja.stringrecognizer.CustomStringType`.
+	"""
 	value: 'StringRef'
 	location: Optional[DerivedStringLocation]
 	custom_type: Optional[stringrecognizer.CustomStringType]

python/constantrenderer.py

@@ -53,6 +53,14 @@ def __getitem__(cls, value):
 
 
 class ConstantRenderer(metaclass=_ConstantRendererMetaClass):
+	"""
+	``class ConstantRenderer`` allows custom rendering of constants in high level representations.
+
+	The :py:func:`render_constant` method will be called when rendering constants that aren't pointers, while the
+	:py:func:`render_constant_pointer` method will be called when rendering constant pointers. The
+	:py:func:`is_valid_for_type` method can be optionally overridden to call the rendering methods only when
+	the expression type matches a custom filter.
+	"""
 	_registered_renderers = []
 	renderer_name = None
 
@@ -61,6 +69,7 @@ def __init__(self, handle=None):
 			self.handle = core.handle_of_type(handle, core.BNConstantRenderer)
 
 	def register(self):
+		"""Registers the constant renderer."""
 		if self.__class__.renderer_name is None:
 			raise ValueError("Renderer name is missing")
 		self._cb = core.BNCustomConstantRenderer()
@@ -117,13 +126,37 @@ def name(self) -> str:
 		return self.__class__.renderer_name
 
 	def is_valid_for_type(self, func: 'highlevelil.HighLevelILFunction', type: 'types.Type') -> bool:
+		"""
+		Determines if the rendering methods should be called for the given expression type. It is optional
+		to override this method. If the method isn't overridden, all expression types are passed to the
+		rendering methods.
+
+		:param func: `HighLevelILFunction` representing the high level function to be rendered
+		:param type: Type of the expression
+		:return: `True` if the constant should be passed to the rendering methods, `False` otherwise
+		"""
 		return True
 
 	def render_constant(
 		self, instr: 'highlevelil.HighLevelILInstruction', type: 'types.Type', val: int,
 		tokens: 'languagerepresentation.HighLevelILTokenEmitter',
 		settings: Optional['function.DisassemblySettings'], precedence: 'enums.OperatorPrecedence'
 	) -> bool:
+		"""
+		Can be overridden to render a constant that is not a pointer. The expression type and value of the
+		expression are given. If the expression is not handled by this constant renderer, this method should
+		return `False`.
+
+		To render a constant, emit the tokens to the `tokens` object and return `True`.
+
+		:param instr: High level expression
+		:param type: Type of the expression
+		:param val: Value of the expression
+		:param tokens: Token emitter for adding the rendered tokens
+		:param settings: Settings for rendering
+		:param precedence: Operator precedence of the expression
+		:return: `True` if the constant was rendered, `False` otherwise
+		"""
 		return False
 
 	def render_constant_pointer(
@@ -132,6 +165,21 @@ def render_constant_pointer(
 		settings: Optional['function.DisassemblySettings'], symbol_display: 'enums.SymbolDisplayType',
 		precedence: 'enums.OperatorPrecedence'
 	) -> bool:
+		"""
+		Can be overridden to render a constant pointer. The expression type and value of the expression are given.
+		If the expression is not handled by this constant renderer, this method should return `False`.
+
+		To render a constant pointer, emit the tokens to the `tokens` object and return `True`.
+
+		:param instr: High level expression
+		:param type: Type of the expression
+		:param val: Value of the expression
+		:param tokens: Token emitter for adding the rendered tokens
+		:param settings: Settings for rendering
+		:param symbol_display: Type of symbol to display
+		:param precedence: Operator precedence of the expression
+		:return: `True` if the constant was rendered, `False` otherwise
+		"""
 		return False