Make changes suggested by Howon, includiing some significant clarifications to the Generate improvements page.

jmacdotorg · jmacdotorg · commit ce799abe3da6 · 2025-05-23T17:23:18.000-04:00
diff --git a/docs/guides/code-review-overview.md b/docs/guides/code-review-overview.md
@@ -19,12 +19,13 @@ a real repository, see [Quickstart](/getting-started/quickstart).
 After you [integrate CodeRabbit with your repository](/platforms), CodeRabbit proceeds
 to automatically review every subsequent pull request, as soon as each one is created.
 
-A CodeRabbit code review consists of a single, multi-part comment attached to the pull request.
-The comment contains a detailed summary and analysis of the changes,
-as well as a listing of problems or areas for potential improvement that it found.
+CodeRabbit performs code reviews by attaching comments to the pull request.
+These comments contain detailed summaries and analyses of the changes,
+as well as listing out problems or areas for potential improvement that it found.
 
-CodeRabbit uses [a variety of open-source linters and security tools](/tools) to provide this analysis. CodeRabbit
-also consults an ensemble of models to further analyze and critique the proposed changes,
+CodeRabbit uses [a variety of open-source linters and security tools](/tools) and a custom
+code verification agent to provide this analysis. CodeRabbit
+also consults several models to further analyze and critique the proposed changes,
 using all of the content of your repository as context. The code-review comment that CodeRabbit attaches
 to your pull request synthesizes and summarizes all of the information collected from these different sources.
 
@@ -41,14 +42,6 @@ perform a code review:
 - If an open pull request that CodeRabbit has already reviewed gets modified with another
   commit, then CodeRabbit performs an incremental review that focuses on the new commit.
 
-### Example code reviews {#examples}
-
-The following real pull requests, hosted on GitHub, demonstrate some example CodeRabbit
-review comments.
-
-- [A modest refactoring of Markdown-based documentation source](https://github.com/coderabbitai/coderabbit-docs/pull/325), demonstrating a CodeRabbit graph analysis.
-- [A large change that added many files](https://github.com/tyaga001/devtoolsacademy/pull/44), demonstrating incremental automated reviews of subsequent commits.
-
 ## Interact with CodeRabbit reviews {#interact}
 
 After CodeRabbit attaches its initial code-review comment to a pull request, you can
diff --git a/docs/guides/commands.md b/docs/guides/commands.md
@@ -96,19 +96,31 @@ pull request:
 @coderabbitai resolve
 ```
 
-## Generate summary text {#summary}
+## Update information about the pull request {#update}
 
-To have CodeRabbit add or update a generated summary of the branch’s proposed changes
+The commands in this section request CodeRabbit to generate and post updated information
+about the pull request itself.
+
+### Update the summary text {#summary}
+
+To have CodeRabbit update the generated summary of the branch’s proposed changes
 to the pull request’s description, post the following comment:
-pull request:
 
 ```text
 @coderabbitai summary
 ```
 
-CodeRabbit appends the summary text to the description under the heading
-"Summary by CodeRabbit". If CodeRabbit has previously added a summary under that
-heading, then it replaces it with the new summary.
+CodeRabbit updates the summary text to the description under the heading
+"Summary by CodeRabbit".
+
+### Diagram the pull request history {#diagram}
+
+To have CodeRabbit post a comment that contains a sequence diagram which visualizes the
+history of the pull request under review, post the following comment:
+
+```text
+@coderabbitai generate sequence diagram
+```
 
 ## Get information about CodeRabbit {#info}
 
diff --git a/docs/guides/generate-improvements.md b/docs/guides/generate-improvements.md
@@ -9,18 +9,33 @@ import ProPlanNotice from '@site/src/components/ProPlanNotice.mdx';
 <ProPlanNotice />
 ```
 
-During a code review, you can command CodeRabbit to address its own review comments
-by generating its own code improvements, which it publishes on separate branches.
+This page is about using CodeRabbit to generate improvements to code under review.
 
 For a general overview of performing code reviews with CodeRabbit, see [Review pull requests](/guides/code-review-overview).
 
 ## Overview of CodeRabbit code generation {#overview}
 
-You can command CodeRabbit to generate any code changes necessary to address its own code review suggestions,
-or you can command it specifically to address inline documentation gaps.
+:::note
+This feature is available only on GitHub.
+:::
+
+You can request CodeRabbit to generate improvements to a branch that it is currently reviewing.
+
+To do this, write out your request prompt in a comment addressed to `@coderabbitai`,
+such as with the following examples:
 
-After you give it a code-generation command, CodeRabbit delivers its suggested improvements by taking these steps:
+- `@coderabbitai Please implement the changes you suggested in your code review.`
+- `@coderabbitai Add input validation with proper error messages to these new functions.`
+- `@coderabbitai Break this large function into smaller, more focused methods.`
 
+Beyond this kind of free-form request, you can also give CodeRabbit keyword-based
+commands for common code-generation requests, as described in [Code generation commands](#commands).
+This includes the `plan` keyword, which acts as shorthand for the first prompt on the
+previous list.
+
+After you give it a code-generation prompt or command, CodeRabbit delivers its suggested improvements by taking these steps:
+
+1. CodeRabbit posts a comment or two to the pull request, detailing its improvement plans.
 1. CodeRabbit publishes a new branch, based on the open pull request's branch, to the remote repository.
 1. CodeRabbit opens a new pull request based on this new branch, and links to it from the original pull request.
 
@@ -40,6 +55,10 @@ your workflow.
 
 ## Code generation commands {#commands}
 
+This section lists short commands that you can give CodeRabbit to have it accomplish
+common code-generation tasks. For more complex tasks, you can instead write out full
+prompts, as described in the previous section.
+
 For a complete CodeRabbit command reference, see [Code review command reference](/reference/review-commands).
 
 ### Generate inline documentation {#docstrings}
@@ -58,10 +77,6 @@ the Git platforms and programming languages that this feature supports, see
 
 ### Generate solutions to open review comments {#plan}
 
-:::note
-This feature is available only on GitHub.
-:::
-
 To have CodeRabbit generate and add a new repository branch with code improvements
 that try to address its own code review comments, post the following comment to the
 pull request:
@@ -70,6 +85,16 @@ pull request:
 @coderabbitai plan
 ```
 
+Using this keyword is essentially shorthand for writing out a prompt like like the following:
+
+```text
+@coderabbitai Implement the changes that you suggested and apply them to this pull request.
+```
+
+If you want to give CodeRabbit more specific implement instructions other than a general
+request to implement its own suggestions, then you can write out those instructions
+as a full prompt, instead of using the one-word `plan` command.
+
 ## What's next {#whats-next}
 
 - [Control and manage code reviews](/guides/commands)
