comments: add Comment.text

scanny · scanny · commit a809d6cc8aec · 2025-06-16T14:24:39.000-07:00
diff --git a/features/doc-add-comment.feature b/features/doc-add-comment.feature
@@ -4,7 +4,6 @@ Feature: Add a comment to a document
   I need a way to add a comment specifying both its content and its reference
 
 
-  @wip
   Scenario: Document.add_comment(runs, text, author, initials)
     Given a document having a comments part
      When I assign comment = document.add_comment(runs, "A comment", "John Doe", "JD")
diff --git a/src/docx/comments.py b/src/docx/comments.py
@@ -144,6 +144,16 @@ def initials(self) -> str | None:
     def initials(self, value: str | None):
         self._comment_elm.initials = value
 
+    @property
+    def text(self) -> str:
+        """The text content of this comment as a string.
+
+        Only content in paragraphs is included and of course all emphasis and styling is stripped.
+
+        Paragraph boundaries are indicated with a newline ("\n")
+        """
+        return "\n".join(p.text for p in self.paragraphs)
+
     @property
     def timestamp(self) -> dt.datetime | None:
         """The date and time this comment was authored.
diff --git a/tests/test_comments.py b/tests/test_comments.py
@@ -209,6 +209,26 @@ def it_knows_the_date_and_time_it_was_authored(self, comments_part_: Mock):
 
         assert comment.timestamp == dt.datetime(2023, 10, 1, 12, 34, 56, tzinfo=dt.timezone.utc)
 
+    @pytest.mark.parametrize(
+        ("cxml", "expected_value"),
+        [
+            ("w:comment{w:id=42}", ""),
+            ('w:comment{w:id=42}/w:p/w:r/w:t"Comment text."', "Comment text."),
+            (
+                'w:comment{w:id=42}/(w:p/w:r/w:t"First para",w:p/w:r/w:t"Second para")',
+                "First para\nSecond para",
+            ),
+            (
+                'w:comment{w:id=42}/(w:p/w:r/w:t"First para",w:p,w:p/w:r/w:t"Second para")',
+                "First para\n\nSecond para",
+            ),
+        ],
+    )
+    def it_can_summarize_its_content_as_text(
+        self, cxml: str, expected_value: str, comments_part_: Mock
+    ):
+        assert Comment(cast(CT_Comment, element(cxml)), comments_part_).text == expected_value
+
     def it_provides_access_to_the_paragraphs_it_contains(self, comments_part_: Mock):
         comment_elm = cast(
             CT_Comment,
