Fields, Links, And Review Notes¶

Field, hyperlink, note, comment, and revision APIs are available on featherdoc::Document. Field and hyperlink operations that can be scoped to a body, header, footer, or section part are also available on featherdoc::TemplatePart.

Typed Signature Guide¶

Field, hyperlink, note, comment, and revision indexes are zero-based and come from the corresponding list_* method. Append methods returning std::size_t return a created count. Methods returning bool report whether a specific indexed item was changed.

Signature	Parameters	Return semantics
`std::vector<field_summary> list_fields() const`	None.	Field summaries in the selected document part.
`bool append_field(std::string_view instruction, std::string_view result_text = {}, field_state_options state = {})`	`instruction`: Word field instruction. `result_text`: displayed result. `state`: dirty/locked options.	`true` when the field was appended.
`bool replace_field(std::size_t field_index, std::string_view instruction, std::string_view result_text = {})`	`field_index`: item from `list_fields()`. `instruction` and `result_text`: replacement values.	`true` when the indexed field was replaced.
`std::size_t append_hyperlink(std::string_view text, std::string_view target)`	`text`: visible hyperlink text. `target`: URL or relationship target.	Created hyperlink count; `0` means nothing was appended.
`std::size_t append_comment(std::string_view selected_text, std::string_view comment_text, std::string_view author = {}, std::string_view initials = {}, std::string_view date = {})`	`selected_text`: text to annotate. `comment_text`: comment body. Metadata arguments are optional.	Created comment count; `0` means input validation or mutation failed.
`bool set_comment_resolved(std::size_t comment_index, bool resolved)`	`comment_index`: item from `list_comments()`. `resolved`: target state.	`true` when the comment state was updated.
`bool accept_revision(std::size_t revision_index)`	`revision_index`: item from `list_revisions()`.	`true` when that revision was accepted.
`std::size_t accept_all_revisions()`	None.	Number of tracked revisions accepted.

Summary Types¶

Type	Key fields	Purpose
`featherdoc::field_summary`	`kind`, `instruction`, `result_text`, `dirty`, `locked`	Describes a simple or complex Word field.
`featherdoc::hyperlink_summary`	`text`, `target`, `anchor`, `external`	Describes an internal or external hyperlink.
`featherdoc::review_note_summary`	`kind`, `author`, `date`, `resolved`, `text`	Describes footnotes, endnotes, comments, and comment replies.
`featherdoc::revision_summary`	`kind`, `author`, `part_entry_name`, `text`	Describes tracked insertions, deletions, and related revision records.

Fields¶

Method	Returns	Purpose
`list_fields() const`	`std::vector<field_summary>`	Enumerate fields in the selected document part.
`append_field(instruction, result_text, state)`	`bool`	Append a simple field instruction and optional display result.
`append_complex_field(instruction, result_text, options)`	`bool`	Append a complex Word field.
`append_page_number_field(state = {})`	`bool`	Append a PAGE field.
`append_total_pages_field(state = {})`	`bool`	Append a NUMPAGES field.
`append_table_of_contents_field(options, result_text)`	`bool`	Append a TOC field.
`append_reference_field(bookmark_name, options, result_text)`	`bool`	Append a REF field that points at a bookmark.
`replace_field(field_index, instruction, result_text)`	`bool`	Replace a field instruction and result by index.

Hyperlinks¶

Method	Returns	Purpose
`list_hyperlinks() const`	`std::vector<hyperlink_summary>`	Enumerate hyperlinks.
`append_hyperlink(text, target)`	`std::size_t`	Append a hyperlink and return the created hyperlink count; `0` means no hyperlink was added.
`replace_hyperlink(hyperlink_index, text, target)`	`bool`	Replace hyperlink text and target.
`remove_hyperlink(hyperlink_index)`	`bool`	Remove one hyperlink.

Notes, Comments, And Revisions¶

Review-note and tracked-change identifiers use the non-negative signed 64-bit range. Allocators scan every relevant document story, including the body, headers, footers, footnotes, endnotes, and comments as applicable. Operations that need more than one identifier reserve the complete set before changing XML; exhaustion returns document_errc::identifier_space_exhausted.

Edits to an existing footnote, endnote, or comment validate the optional part, target index, required paragraph metadata, and identifier capacity before creating relationships, Content Types entries, or review parts. Every affected XML document, relationship, Content Types entry, review sidecar, and dirty flag is prepared before one publication step. Missing or out-of-range targets, identifier exhaustion, pugixml allocation failure, and std::bad_alloc therefore leave the DOM, package metadata, and existing handles unchanged. Allocation failure is reported through last_error() as std::errc::not_enough_memory.

Method	Returns	Purpose
`list_footnotes() const` / `list_endnotes() const`	`std::vector<review_note_summary>`	Enumerate footnotes or endnotes.
`append_footnote(reference_text, note_text)`	`std::size_t`	Append a footnote.
`append_endnote(reference_text, note_text)`	`std::size_t`	Append an endnote.
`replace_footnote(note_index, note_text)`	`bool`	Replace one footnote.
`remove_endnote(note_index)`	`bool`	Remove one endnote.
`list_comments() const`	`std::vector<review_note_summary>`	Enumerate comments.
`append_comment(selected_text, comment_text, author, initials, date)`	`std::size_t`	Append a comment anchored to selected text.
`append_text_range_comment(start_paragraph_index, start_text_offset, end_paragraph_index, end_text_offset, comment_text, author, initials, date)`	`std::size_t`	Comment a text range.
`set_comment_resolved(comment_index, resolved)`	`bool`	Mark a comment resolved or unresolved.
`list_revisions() const`	`std::vector<revision_summary>`	Enumerate tracked revisions.
`accept_revision(revision_index)` / `reject_revision(revision_index)`	`bool`	Resolve one revision.
`accept_all_revisions()` / `reject_all_revisions()`	`std::size_t`	Resolve all tracked revisions.

Example¶

featherdoc::Document doc{"review.docx"};
doc.open();

auto body = doc.body_template();
body.append_page_number_field();
body.append_hyperlink("FeatherDoc", "https://github.com/wuxianggujun/FeatherDoc");

for (const auto &comment : doc.list_comments()) {
    if (!comment.resolved) {
        doc.set_comment_resolved(comment.index, true);
    }
}