This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/document-authoring/review-and-collaboration/comments-and-review-workflows.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Review documents with comments in Document Authoring

Review documents with comments

Markdown version of this page, suitable for AI agents and automation

Before you start, ensure the Document Authoring library is installed and running. Refer to the getting started guide.

Document Authoring includes built-in comment workflows for review. Comments anchor to document text and appear beside the document. Reviewers can add comments from the Insert menu or context menu, reply in threads, edit comment text, resolve discussions, reopen resolved threads, and delete comments when they’re no longer needed.

The example code omits error handling. Add it before using this code in production.

Set the author when creating the editor

Use UIOptions.author to set the author name used for new comments, replies, and tracked changes:

const editor = await docAuthSystem.createEditor(
  document.getElementById('editor'),
  {
    ui: {
      author: 'Jane Reviewer',
    },
  },
);

If you don’t provide an author name, comments use a localized anonymous label.

Change the author at runtime

Use editor.setAuthor(name) to update the current author when the active user changes:

editor.setAuthor('Legal Team');

Read the current author with editor.getAuthor():

const currentAuthor = editor.getAuthor();
console.log(currentAuthor);

Clear the current author to fall back to the anonymous label:

editor.setAuthor('');

Add comments in the editor UI

To add a comment in the editor:

  1. Select the text to review.
  2. In the toolbar’s Insert menu, select Comment — or right-click the selection and choose Insert → Comment. (Both options are available only when text is selected.)
  3. Enter the comment text.

The comment attaches to the selected text and appears in the document’s comment thread list.

Reply to and manage comment threads

Document Authoring supports threaded comment discussions. Reviewers can:

  • Reply to an existing comment thread
  • Edit comment or reply text
  • Resolve a thread when the discussion is complete
  • Reopen a resolved thread if more review is needed
  • Delete a comment thread

This keeps document discussions anchored to the exact text under review.

Use comments as an AI audit trail

Document Authoring AI can ask the editor to create review comments when it applies agentic write tool calls. Use this when you want AI-generated edits to include reviewer-facing explanations, such as why a clause was changed or which style rule triggered a rewrite.

Review comments created by Document Authoring AI are ordinary comment threads anchored to the changed text, so reviewers can reply, resolve, reopen, or delete them in the same UI described above. Your app still controls the policy: Enable comment creation with the AI toolkit’s reviewComments: "create" option, and use Review mode when you also want the edit itself recorded as a tracked change.

For the AI-specific setup, refer to the agentic tools and review and approval guides.

Use comments together with programmatic review flows

Use the programmatic document API inside a transaction to inspect or manage comment threads in code. For example, query open threads with draft.commentThreads(), add replies, or resolve threads programmatically:

const currentDoc = editor.currentDocument();


await currentDoc.transaction(async ({ draft }) => {
  const openThreads = draft.commentThreads().all({ status: 'open' });


  for (const thread of openThreads) {
    thread.reply('Reviewed by automation.');
    thread.resolve();
  }


  return true;
});

For a full walkthrough of the transaction API, refer to the programmatic editing guide.

Learn more