Skip to content

[codex] fix comments guide API attributes #1554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Sean-Kenneth-Doherty wants to merge 1 commit into
base: master
Choose a base branch
from
+7 −6
Open

[codex] fix comments guide API attributes #1554

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions docs/user/comments.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ and size, both paragraph and character styles, hyperlinks, images, and tables. N
tables do not appear in the comment as displayed in the *comment-sidebar* although they
do apper in the *reviewing-pane*.

**Comment Metadata.** Each comment can be assigned *author*, *initals*, and *date*
**Comment Metadata.** Each comment can be assigned *author*, *initials*, and *date*
metadata. In Word, these fields are assigned automatically based on values in ``Settings
> User`` of the installed Word application. These might be configured automatically in
an enterprise installation, based on the user account, but by default they are empty.
Expand All @@ -66,7 +66,8 @@ an enterprise installation, based on the user account, but by default they are e
the user name is not configured. *initials* is optional, but always set by Word, to the
empty string if not configured. *date* is also optional, but always set by Word to the
UTC date and time the comment was added, with seconds resolution (no milliseconds or
microseconds).
microseconds). The comment date is exposed in *python-docx* as
:attr:`.Comment.timestamp`.

**Additional Features.** Later versions of Word allow a comment to be *resolved*. A
comment in this state will appear grayed-out in the Word UI. Later versions of Word also
Expand All @@ -90,19 +91,19 @@ A simple example is adding a comment to a paragraph::

>>> comment = document.add_comment(
... runs=paragraph.runs,
... text="I have this to say about that"
... text="I have this to say about that",
... author="Steve Canny",
... initials="SC",
... )
>>> comment
<docx.comments.Comment object at 0x02468ACE>
>>> comment.id
>>> comment.comment_id
0
>>> comment.author
'Steve Canny'
>>> comment.initials
'SC'
>>> comment.date
>>> comment.timestamp
datetime.datetime(2025, 6, 11, 20, 42, 30, 0, tzinfo=datetime.timezone.utc)
>>> comment.text
'I have this to say about that'
Expand Down Expand Up @@ -131,7 +132,7 @@ The comments collection supports random access to a comment by its id::
Adding rich content to a comment
--------------------------------

A comment is a _block-item container_, just like the document body or a table cell, so
A comment is a *block-item container*, just like the document body or a table cell, so
it can contain any content that can appear in those places. It does not contain
page-layout sections and cannot contain a comment reference, but it can contain multiple
paragraphs and/or tables, and runs within paragraphs can have emphasis such as bold or
Expand Down