Skip to content

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 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 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 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 ea is a tail byte or comment_kind is ALL.

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 lines is 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.

ExtraCommentKind

Bases: Enum

Enumeration for extra comment positions.

Attributes:

ANTERIOR class-attribute instance-attribute

ANTERIOR = 'anterior'

POSTERIOR class-attribute instance-attribute

POSTERIOR = 'posterior'