Skip to content

fix: ensure CommentReference character style is defined when adding a comment - #1610

Open
VenkateswarluNagineni wants to merge 1 commit into
python-openxml:masterfrom
VenkateswarluNagineni:fix/comment-reference-style-missing
Open

fix: ensure CommentReference character style is defined when adding a comment#1610
VenkateswarluNagineni wants to merge 1 commit into
python-openxml:masterfrom
VenkateswarluNagineni:fix/comment-reference-style-missing

Conversation

@VenkateswarluNagineni

Copy link
Copy Markdown

What this fixes

Closes #1609.

Document.add_comment() writes <w:rStyle w:val="CommentReference"/> into the
reference run but never adds the matching style definition to styles.xml. The default
Document() template doesn't contain it either, so the reference mark ends up with a
dangling rStyle and falls back to default run formatting instead of the intended 8-pt
"annotation reference" appearance. Word and LibreOffice tolerate this silently, but the
mark is visually wrong and opens a subtle trap for any caller that inspects styles.

Fix

Styles._ensure_comment_reference_style() registers the built-in style on first use.
Document.add_comment() calls it before marking the comment range. The method is
idempotent — documents that already carry the style (e.g., re-opened Word files) are
left unchanged.

The style definition matches what Word 365 writes:

Field Value
w:name annotation reference
w:styleId CommentReference (matches the id the reference run uses)
w:basedOn DefaultParagraphFont
w:uiPriority 99
w:semiHidden / w:unhideWhenUsed present
w:rPr/w:sz 16 (8 pt in half-points)

Changes

  • src/docx/styles/styles.py: add _ensure_comment_reference_style() + Pt import
  • src/docx/document.py: call self.styles._ensure_comment_reference_style() in add_comment()
  • features/doc-add-comment.feature: new acceptance scenario
  • features/steps/comments.py: given step for fresh document without the style + then assertion step

Testing

pytest tests/ -q -k "comment or style"
# 251 passed

Acceptance tests require behave (not available in this environment); the new scenario is
readable and can be verified by inspection.

Verification script:

from docx import Document

d = Document()
p = d.add_paragraph("Some text.")
print(d.styles._element.get_by_id("CommentReference"))  # None — not there yet

d.add_comment(runs=p.runs[0], text="A comment", author="Reviewer")
style = d.styles._element.get_by_id("CommentReference")
print(style.name_val)   # "annotation reference"
print(style.styleId)    # "CommentReference"
print(style.type)       # CHARACTER (2)

… comment (python-openxmlgh-1609)

add_comment() writes <w:rStyle w:val="CommentReference"/> into the reference
run but never adds the matching style definition to styles.xml.  A default
Document() template doesn't contain it either, so the reference mark ends up
with a dangling rStyle and falls back to default run formatting instead of
the intended 8-pt "annotation reference" appearance.

Styles._ensure_comment_reference_style() is added to register the built-in
style on first use.  Document.add_comment() calls it before marking the
comment range.  The method is idempotent: repeated calls and documents that
already carry the style from a prior Word session are left unchanged.

The style definition matches what Word 365 writes:
  • name: "annotation reference"
  • styleId: "CommentReference"   (matches the id the reference run uses)
  • basedOn: "DefaultParagraphFont"
  • uiPriority: 99 / semiHidden / unhideWhenUsed
  • rPr: sz 8 pt (16 half-points)

Acceptance test: doc-add-comment.feature scenario verifies that
styles.xml contains a CHARACTER style with styleId "CommentReference"
after add_comment() is called on a fresh document.

Fixes python-openxml#1609
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

add_comment() references the "CommentReference" character style without defining it

1 participant