update error message and error docs

crates/next-custom-transforms/src/transforms/lint_codemod_comments.rs

@@ -44,9 +44,10 @@ where
             };
             let action = trimmed_text.replace(COMMENT_ERROR_PREFIX, "");
             let err_message = format!(
-                "You have unresolved @next/codemod comment \"{}\" that need to be reviewed, \
-                 please address and remove them to proceed with the build.\nYou can also bypass \
-                 the build error by replacing \"{}\" with \"{}\".",
+                "You have unresolved @next/codemod comment \"{}\" that needs review.\nAfter \
+                 review, either remove the comment if you made the necessary changes or replace \
+                 \"{}\" with \"{}\" to bypass the build error if no action at this line can be \
+                 taken.\n",
                 action.trim(),
                 COMMENT_ERROR_PREFIX,
                 COMMENT_BYPASS_PREFIX

errors/sync-dynamic-apis.mdx

@@ -64,6 +64,31 @@ function Page({ params }) {
 }
 ```
 
+### Unmigratable Cases
+
+If Next.js codemod found anything that is not able to be migrated by the codemod, it will leave a comment with `@next-codemod-error` prefix and the suggested action, for example:
+In this case, you need to manually await the call to `cookies()`, and change the function to async. Then refactor the usages of the function to be properly awaited:
+
+```ts
+export function MyCookiesComponent() {
+  const c =
+    /* @next-codemod-error Manually await this call, if it's a Server Component */
+    cookies()
+  return c.get('name')
+}
+```
+
+### Enforced Migration with Linter
+
+If you didn't address the comments that starting with `@next-codemod-error` left by codemod, Next.js will error in the dev and build to enforce you to address the issues.
+You can review the changes and follow the suggestion in the comments. You can either make the necessary changes then remove the comment, or replace the comment prefix `@next-codemod-error` with `@next-codemod-ignore`
+if there's no action need to be taken. Comment prefix `@next-codemod-ignore` will bypass the build error.
+
+```diff
+- /* @next-codemod-error <suggested message> */
++ /* @next-codemod-ignore */
+```
+
 > **Good to know**:
 >
 > You can delay unwrapping the Promise (either with `await` or `React.use`) until you actually need to consume the value.

test/e2e/app-dir/error-on-next-codemod-comment/error-on-next-codemod-comment.test.ts

@@ -34,14 +34,16 @@ describe('app-dir - error-on-next-codemod-comment', () => {
             4 | }
             5 |
 
-          You have unresolved @next/codemod comment "remove jsx of next line" that need to be reviewed, please address and remove them to proceed with the build.
-          You can also bypass the build error by replacing "@next-codemod-error" with "@next-codemod-ignore"."
+          You have unresolved @next/codemod comment "remove jsx of next line" that needs review.
+          After review, either remove the comment if you made the necessary changes or replace "@next-codemod-error" with "@next-codemod-ignore" to bypass the build error if no action at this line can be taken."
         `)
       } else {
         expect(await getRedboxSource(browser)).toMatchInlineSnapshot(`
           "./app/page.tsx
-          Error:   x You have unresolved @next/codemod comment "remove jsx of next line" that need to be reviewed, please address and remove them to proceed with the build.
-            | You can also bypass the build error by replacing "@next-codemod-error" with "@next-codemod-ignore".
+          Error:   x You have unresolved @next/codemod comment "remove jsx of next line" that needs review.
+            | After review, either remove the comment if you made the necessary changes or replace "@next-codemod-error" with "@next-codemod-ignore" to bypass the build error if no action at this line can
+            | be taken.
+            | 
              ,-[2:1]
            1 | export default function Page() {
            2 |   // @next-codemod-error remove jsx of next line