Comments
comments
Classes:
-
CommentInfo–Represents information about a Comment.
-
CommentKind–Enumeration for IDA comment types.
-
Comments–Provides access to user-defined comments in the IDA database.
-
ExtraCommentKind–Enumeration for extra comment positions.
CommentInfo
dataclass
CommentInfo(ea: ea_t, comment: str, repeatable: bool)
Represents information about a Comment.
Attributes:
-
comment(str) – -
ea(ea_t) – -
repeatable(bool) –
comment
instance-attribute
comment: str
ea
instance-attribute
ea: ea_t
repeatable
instance-attribute
repeatable: bool
CommentKind
Bases: Enum
Enumeration for IDA comment types.
Attributes:
-
ALL– -
REGULAR– -
REPEATABLE–
ALL
class-attribute
instance-attribute
ALL = 'all'
REGULAR
class-attribute
instance-attribute
REGULAR = 'regular'
REPEATABLE
class-attribute
instance-attribute
REPEATABLE = 'repeatable'
Comments
Comments(database: Database)
Bases: DatabaseEntity
Provides access to user-defined comments in the IDA database.
Can be used to iterate over all comments in the opened database.
IDA supports two types of comments: - Regular comments: Displayed at specific addresses - Repeatable comments: Displayed at all references to the same address
Parameters:
-
database(Database) –Reference to the active IDA database.
Methods:
-
append_at–Appends text to a comment at the specified address.
-
delete_at–Deletes a comment at the specified address.
-
delete_extra_at–Deletes a specific extra comment.
-
delete_extra_lines_at–Deletes all extra comment lines of one kind at the specified address.
-
get_all–Creates an iterator for comments in the database.
-
get_all_extra_at–Gets all extra comments of a specific kind.
-
get_at–Retrieves the comment at the specified address.
-
get_combined_at–Combines the selected comments at an address into one text block.
-
get_extra_at–Gets a specific extra comment.
-
set_at–Sets a comment at the specified address.
-
set_extra_at–Sets an extra comment at the specified address and index.
-
set_extra_lines_at–Replaces all extra comment lines of one kind at the specified address.
Attributes:
-
database(Database) –Get the database reference, guaranteed to be non-None when called from
-
m_database–
database
property
database: Database
Get the database reference, guaranteed to be non-None when called from methods decorated with @check_db_open.
Returns:
-
Database–The active database instance.
Note
This property should only be used in methods decorated with @check_db_open, which ensures m_database is not None.
m_database
instance-attribute
m_database = database
append_at
append_at(
ea: ea_t,
comment: str,
comment_kind: CommentKind = REGULAR,
) -> bool
Appends text to a comment at the specified address.
If the selected comment does not exist, it is created with the given text. Otherwise, a newline followed by the supplied text is appended. This method always works on the item comment. Function comments are managed by the functions API.
Parameters:
-
ea(ea_t) –The effective address. Must not be a tail byte of a multi-byte item.
-
comment(str) –The comment text to append.
-
comment_kind(CommentKind, default:REGULAR) –Type of comment to append to (REGULAR or REPEATABLE).
Raises:
-
InvalidEAError–If the effective address is invalid.
-
InvalidParameterError–If
eais a tail byte orcomment_kindisALL.
Returns:
-
bool–True if the comment was successfully appended, False otherwise.
Warning
IDA caps regular and repeatable comments at 1024 bytes of UTF-8 and silently truncates longer text, so appending to a comment near that limit drops the excess even though True is returned.
delete_at
delete_at(
ea: int, comment_kind: CommentKind = REGULAR
) -> None
Deletes a comment at the specified address.
Parameters:
-
ea(int) –The effective address.
-
comment_kind(CommentKind, default:REGULAR) –Type of comment to delete (REGULAR or REPEATABLE).
Raises:
-
InvalidEAError–If the effective address is invalid.
delete_extra_at
delete_extra_at(
ea: int, index: int, kind: ExtraCommentKind
) -> bool
Deletes a specific extra comment.
Parameters:
-
ea(int) –The effective address.
-
index(int) –The comment index (0-based).
-
kind(ExtraCommentKind) –ANTERIOR or POSTERIOR.
Raises:
-
InvalidEAError–If the effective address is invalid.
Returns:
-
bool–True if successful.
delete_extra_lines_at
delete_extra_lines_at(
ea: ea_t, kind: ExtraCommentKind
) -> bool
Deletes all extra comment lines of one kind at the specified address.
Lines stored after a gap, which are invisible in the listing, are deleted as well.
Parameters:
-
ea(ea_t) –The effective address.
-
kind(ExtraCommentKind) –ANTERIOR or POSTERIOR.
Raises:
-
InvalidEAError–If the effective address is invalid.
Returns:
-
bool–True if every line was successfully deleted, False otherwise.
get_all
get_all(
comment_kind: CommentKind = REGULAR,
) -> Iterator[CommentInfo]
Creates an iterator for comments in the database.
Parameters:
-
comment_kind(CommentKind, default:REGULAR) –Type of comments to retrieve: - CommentKind.REGULAR: Only regular comments - CommentKind.REPEATABLE: Only repeatable comments - CommentKind.ALL: Both regular and repeatable comments
Yields:
-
CommentInfo–Tuples of (address, comment_text, is_repeatable) for each comment found.
get_all_extra_at
get_all_extra_at(
ea: int, kind: ExtraCommentKind
) -> Iterator[str]
Gets all extra comments of a specific kind.
Parameters:
-
ea(int) –The effective address.
-
kind(ExtraCommentKind) –ANTERIOR or POSTERIOR.
Raises:
-
InvalidEAError–If the effective address is invalid.
Yields:
-
str–Comment strings in order.
get_at
get_at(
ea: ea_t, comment_kind: CommentKind = REGULAR
) -> Optional[CommentInfo]
Retrieves the comment at the specified address.
Parameters:
-
ea(ea_t) –The effective address.
-
comment_kind(CommentKind, default:REGULAR) –Type of comment to retrieve (REGULAR or REPEATABLE).
Raises:
-
InvalidEAError–If the effective address is invalid.
Returns:
-
Optional[CommentInfo]–The comment string, or None if no comment exists.
get_combined_at
get_combined_at(
ea: ea_t,
*,
include_regular: bool = True,
include_repeatable: bool = True,
include_anterior: bool = True,
include_posterior: bool = True,
) -> Optional[str]
Combines the selected comments at an address into one text block.
Lines are returned in listing order: anterior comments, the regular or repeatable comment, and posterior comments. Matching the listing behavior, the repeatable comment is used only when no regular comment is included. Extra comment lines stored after a missing index are omitted. On a tail byte, the regular and repeatable comments are read from the item head.
Parameters:
-
ea(ea_t) –The effective address.
-
include_regular(bool, default:True) –Include the regular comment.
-
include_repeatable(bool, default:True) –Include the repeatable comment.
-
include_anterior(bool, default:True) –Include anterior comment lines.
-
include_posterior(bool, default:True) –Include posterior comment lines.
Raises:
-
InvalidEAError–If the effective address is invalid.
Returns:
-
Optional[str]–The selected comments joined by newlines, or None if none exist.
get_extra_at
get_extra_at(
ea: int, index: int, kind: ExtraCommentKind
) -> Optional[str]
Gets a specific extra comment.
Parameters:
-
ea(int) –The effective address.
-
index(int) –The comment index (0-based).
-
kind(ExtraCommentKind) –ANTERIOR or POSTERIOR.
Raises:
-
InvalidEAError–If the effective address is invalid.
Returns:
-
Optional[str]–The comment text or None if not found.
set_at
set_at(
ea: int,
comment: str,
comment_kind: CommentKind = REGULAR,
) -> bool
Sets a comment at the specified address.
Parameters:
-
ea(int) –The effective address.
-
comment(str) –The comment text to assign.
-
comment_kind(CommentKind, default:REGULAR) –Type of comment to set (REGULAR or REPEATABLE).
Raises:
-
InvalidEAError–If the effective address is invalid.
Returns:
-
bool–True if the comment was successfully set, False otherwise.
set_extra_at
set_extra_at(
ea: int,
index: int,
comment: str,
kind: ExtraCommentKind,
) -> bool
Sets an extra comment at the specified address and index.
Parameters:
-
ea(int) –The effective address.
-
index(int) –The comment index (0-based).
-
comment(str) –The comment text.
-
kind(ExtraCommentKind) –ANTERIOR or POSTERIOR.
Raises:
-
InvalidEAError–If the effective address is invalid.
Returns:
-
bool–True if successful.
set_extra_lines_at
set_extra_lines_at(
ea: ea_t, lines: Iterable[str], kind: ExtraCommentKind
) -> bool
Replaces all extra comment lines of one kind at the specified address.
Passing an empty iterable deletes all lines of that kind. The input iterable is consumed before the existing comments are changed. A line containing line breaks is split into separate comment lines.
Parameters:
-
ea(ea_t) –The effective address.
-
lines(Iterable[str]) –Comment lines in display order, at most 999 for ANTERIOR and 1000 for POSTERIOR.
-
kind(ExtraCommentKind) –ANTERIOR or POSTERIOR.
Raises:
-
InvalidEAError–If the effective address is invalid.
-
InvalidParameterError–If
linesis a single string instead of an iterable of strings, contains a non-string element, or exceeds the supported line count. The existing comment lines are left unchanged in this case.
Returns:
-
bool–True if the existing lines were deleted and every new line was
-
bool–successfully set, False otherwise.
Note
IDA does not provide a transactional bulk update. The existing lines are deleted before the new ones are written, so if setting a line fails, the original lines are already lost and only a partial replacement remains stored.
Warning
IDA caps each line at 1024 bytes of UTF-8 and silently truncates longer lines even though True is returned.