pub struct Comment {
pub id: u32,
pub author: Option<String>,
pub initials: Option<String>,
pub date: Option<String>,
pub blocks: Vec<Block>,
}Expand description
A single comment’s content (<w:comment>, CT_Comment), declared in word/comments.xml and
anchored to a range of the body via Run.comment_ids — see that field’s doc comment for how the
underlying w:commentRangeStart/w:commentRangeEnd/w:commentReference markers are derived
automatically rather than modeled here.
CT_Comment extends CT_TrackChange (id, author, date) and adds initials, plus the
same block-level content model as the document body (EG_BlockLevelElts, like
Note/HeaderFooter). A <w:annotationRef/> (CT_Empty) may optionally mark this
comment’s own reference mark inside its content — not modeled: ECMA-376 §2.13.4.1 explicitly
allows omitting it (“an annotation reference mark may be added. by the consumer”), and Word’s
Reviewing pane balloon already shows author/date/initials from this element’s own
attributes without needing it, unlike a footnote/endnote’s number marker (NoteMarker), which
genuinely is the only thing that renders the note’s number at all.
Fields§
§id: u32This comment’s id, referenced by Run.comment_ids.
The comment’s author (w:author), shown in Word’s Reviewing pane.
initials: Option<String>The author’s initials (w:initials), shown next to the comment’s reference mark in the
body.
date: Option<String>When the comment was made (w:date), stored verbatim as a plain xs:dateTime string (e.g.
"2024-01-01T12:00:00Z") rather than parsed into a real date/time type — this crate doesn’t
otherwise need a date/time dependency, so round-tripping this one attribute as text avoids
adding one just for this. The caller is responsible for a valid xs:dateTime value if
Word’s own date display matters.
blocks: Vec<Block>The blocks that make up this comment’s content, in order.
Implementations§
Source§impl Comment
impl Comment
Sourcepub fn new(id: u32) -> Comment
pub fn new(id: u32) -> Comment
Creates an empty comment with the given id and no author/initials/ date set.
Sourcepub fn with_text(id: u32, text: impl Into<String>) -> Comment
pub fn with_text(id: u32, text: impl Into<String>) -> Comment
A ready-made comment: a single paragraph with the given text. Use Comment::new plus
with_paragraph/with_table instead for full control (e.g. a comment spanning several
paragraphs). Unlike Note::footnote_with_text, no marker run is needed at the start — see
Comment’s doc comment for why annotationRef isn’t modeled.
Examples found in repository?
15fn main() -> office_toolkit::Result<()> {
16 let path = output_path("docx_navigation_and_annotations.docx");
17
18 let document =
19 Document::new()
20 .with_paragraph(heading(
21 "Hyperlinks: external, and internal to a bookmark",
22 false,
23 ))
24 .with_paragraph(
25 Paragraph::new()
26 .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
27 "https://www.rust-lang.org".to_string(),
28 )))
29 .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
30 "https://www.rust-lang.org".to_string(),
31 )))
32 .with_run(
33 Run::new("down to the bookmark")
34 .with_hyperlink(Hyperlink::Internal("Target".to_string())),
35 ),
36 )
37 .with_paragraph(
38 Paragraph::new()
39 .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
40 .with_run(
41 Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
42 ),
43 )
44 .with_paragraph(heading("Comments", true))
45 .with_paragraph(
46 Paragraph::new()
47 .with_run(Run::new("This sentence "))
48 .with_run(Run::new("needs a second look").with_comment(0))
49 .with_run(Run::new(" before it ships.")),
50 )
51 .with_comment(
52 Comment::with_text(0, "Please double-check this claim.")
53 .with_author("Reviewer")
54 .with_initials("RV"),
55 )
56 .with_paragraph(heading("Footnotes and endnotes", true))
57 .with_paragraph(
58 Paragraph::with_text("A claim that needs a footnote")
59 .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
60 .with_run(Run::new(", and another that needs an endnote"))
61 .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
62 )
63 .with_footnote(Note::footnote_with_text(
64 1,
65 "The footnote's own explanatory text.",
66 ))
67 .with_endnote(Note::endnote_with_text(
68 1,
69 "The endnote's own explanatory text.",
70 ))
71 .with_paragraph(heading("A structured document tag (content control)", true))
72 .with_paragraph(Paragraph::with_text("Before the content control:"))
73 .with_structured_document_tag(
74 StructuredDocumentTag::new()
75 .with_id(42)
76 .with_tag("CustomerName")
77 .with_alias("Customer name")
78 .with_paragraph(Paragraph::with_text("Acme Corp.")),
79 );
80
81 document.save_to_file(&path)?;
82 println!("Wrote {}", path.display());
83 Ok(())
84}Sets the comment’s author and returns it for chaining.
Examples found in repository?
15fn main() -> office_toolkit::Result<()> {
16 let path = output_path("docx_navigation_and_annotations.docx");
17
18 let document =
19 Document::new()
20 .with_paragraph(heading(
21 "Hyperlinks: external, and internal to a bookmark",
22 false,
23 ))
24 .with_paragraph(
25 Paragraph::new()
26 .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
27 "https://www.rust-lang.org".to_string(),
28 )))
29 .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
30 "https://www.rust-lang.org".to_string(),
31 )))
32 .with_run(
33 Run::new("down to the bookmark")
34 .with_hyperlink(Hyperlink::Internal("Target".to_string())),
35 ),
36 )
37 .with_paragraph(
38 Paragraph::new()
39 .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
40 .with_run(
41 Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
42 ),
43 )
44 .with_paragraph(heading("Comments", true))
45 .with_paragraph(
46 Paragraph::new()
47 .with_run(Run::new("This sentence "))
48 .with_run(Run::new("needs a second look").with_comment(0))
49 .with_run(Run::new(" before it ships.")),
50 )
51 .with_comment(
52 Comment::with_text(0, "Please double-check this claim.")
53 .with_author("Reviewer")
54 .with_initials("RV"),
55 )
56 .with_paragraph(heading("Footnotes and endnotes", true))
57 .with_paragraph(
58 Paragraph::with_text("A claim that needs a footnote")
59 .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
60 .with_run(Run::new(", and another that needs an endnote"))
61 .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
62 )
63 .with_footnote(Note::footnote_with_text(
64 1,
65 "The footnote's own explanatory text.",
66 ))
67 .with_endnote(Note::endnote_with_text(
68 1,
69 "The endnote's own explanatory text.",
70 ))
71 .with_paragraph(heading("A structured document tag (content control)", true))
72 .with_paragraph(Paragraph::with_text("Before the content control:"))
73 .with_structured_document_tag(
74 StructuredDocumentTag::new()
75 .with_id(42)
76 .with_tag("CustomerName")
77 .with_alias("Customer name")
78 .with_paragraph(Paragraph::with_text("Acme Corp.")),
79 );
80
81 document.save_to_file(&path)?;
82 println!("Wrote {}", path.display());
83 Ok(())
84}Sourcepub fn with_initials(self, initials: impl Into<String>) -> Comment
pub fn with_initials(self, initials: impl Into<String>) -> Comment
Sets the author’s initials and returns it for chaining.
Examples found in repository?
15fn main() -> office_toolkit::Result<()> {
16 let path = output_path("docx_navigation_and_annotations.docx");
17
18 let document =
19 Document::new()
20 .with_paragraph(heading(
21 "Hyperlinks: external, and internal to a bookmark",
22 false,
23 ))
24 .with_paragraph(
25 Paragraph::new()
26 .with_run(Run::new("Visit the ").with_hyperlink(Hyperlink::External(
27 "https://www.rust-lang.org".to_string(),
28 )))
29 .with_run(Run::new("or jump ").with_hyperlink(Hyperlink::External(
30 "https://www.rust-lang.org".to_string(),
31 )))
32 .with_run(
33 Run::new("down to the bookmark")
34 .with_hyperlink(Hyperlink::Internal("Target".to_string())),
35 ),
36 )
37 .with_paragraph(
38 Paragraph::new()
39 .with_run(Run::new("Here is ").with_bookmark(Bookmark::new(0, "Target")))
40 .with_run(
41 Run::new("the bookmarked text.").with_bookmark(Bookmark::new(0, "Target")),
42 ),
43 )
44 .with_paragraph(heading("Comments", true))
45 .with_paragraph(
46 Paragraph::new()
47 .with_run(Run::new("This sentence "))
48 .with_run(Run::new("needs a second look").with_comment(0))
49 .with_run(Run::new(" before it ships.")),
50 )
51 .with_comment(
52 Comment::with_text(0, "Please double-check this claim.")
53 .with_author("Reviewer")
54 .with_initials("RV"),
55 )
56 .with_paragraph(heading("Footnotes and endnotes", true))
57 .with_paragraph(
58 Paragraph::with_text("A claim that needs a footnote")
59 .with_run(Run::with_note_reference(NoteReference::Footnote(1)))
60 .with_run(Run::new(", and another that needs an endnote"))
61 .with_run(Run::with_note_reference(NoteReference::Endnote(1))),
62 )
63 .with_footnote(Note::footnote_with_text(
64 1,
65 "The footnote's own explanatory text.",
66 ))
67 .with_endnote(Note::endnote_with_text(
68 1,
69 "The endnote's own explanatory text.",
70 ))
71 .with_paragraph(heading("A structured document tag (content control)", true))
72 .with_paragraph(Paragraph::with_text("Before the content control:"))
73 .with_structured_document_tag(
74 StructuredDocumentTag::new()
75 .with_id(42)
76 .with_tag("CustomerName")
77 .with_alias("Customer name")
78 .with_paragraph(Paragraph::with_text("Acme Corp.")),
79 );
80
81 document.save_to_file(&path)?;
82 println!("Wrote {}", path.display());
83 Ok(())
84}Sourcepub fn with_date(self, date: impl Into<String>) -> Comment
pub fn with_date(self, date: impl Into<String>) -> Comment
Sets the comment’s date (a plain xs:dateTime string, e.g. "2024-01-01T12:00:00Z" — see
the field’s doc comment) and returns it for chaining.
Sourcepub fn with_paragraph(self, paragraph: Paragraph) -> Comment
pub fn with_paragraph(self, paragraph: Paragraph) -> Comment
Appends a paragraph block and returns the comment for chaining.
Sourcepub fn with_table(self, table: Table) -> Comment
pub fn with_table(self, table: Table) -> Comment
Appends a table block and returns the comment for chaining.
Sourcepub fn paragraphs(&self) -> impl Iterator<Item = &Paragraph>
pub fn paragraphs(&self) -> impl Iterator<Item = &Paragraph>
Iterates over this comment’s paragraphs only, skipping tables.