Improve comments and API naming

Author: philipp-spiess

integrations/upgrade/js-config.test.ts

@@ -2,7 +2,7 @@ import { expect } from 'vitest'
 import { css, json, test, ts } from '../utils'
 
 test(
-  `upgrades a simple JS config file to CSS`,
+  `upgrade JS config files with flat theme values, darkMode, and content fields`,
   {
     fs: {
       'package.json': json`

packages/@tailwindcss-upgrade/src/codemods/migrate-config.ts

@@ -63,9 +63,8 @@ export function migrateConfig(
       cssConfig.append(postcss.parse(css + jsConfigMigration.css))
     }
 
-    // Inject the `@config` in a sensible place
-    // 1. Below the last `@import`
-    // 2. At the top of the file
+    // Inject the `@config` directive after the last `@import` or at the
+    // top of the file if no `@import` rules are present
     let locationNode = null as AtRule | null
 
     walk(root, (node) => {
@@ -99,10 +98,9 @@ export function migrateConfig(
 
     if (!hasTailwindImport) return
 
-    // - If a full `@import "tailwindcss"` is present, we can inject the
-    //   `@config` directive directly into this stylesheet.
-    // - If we are the root file (no parents), then we can inject the `@config`
-    //   directive directly into this file as well.
+    // If a full `@import "tailwindcss"` is present or this is the root
+    // stylesheet, we can inject the `@config` directive directly into this
+    // file.
     if (hasFullTailwindImport || sheet.parents.size <= 0) {
       injectInto(sheet)
       return
@@ -134,7 +132,7 @@ function relativeToStylesheet(sheet: Stylesheet, absolute: string) {
   if (relative[0] !== '.') {
     relative = `./${relative}`
   }
-  // Ensure relative is a posix style path since we will merge it with the
+  // Ensure relative is a POSIX style path since we will merge it with the
   // glob.
   return normalizePath(relative)
 }

packages/@tailwindcss-upgrade/src/migrate-js-config.ts

@@ -31,9 +31,9 @@ export async function migrateJsConfig(
     fs.readFile(fullConfigPath, 'utf-8'),
   ])
 
-  if (!isSimpleConfig(unresolvedConfig, source)) {
+  if (!canMigrateConfig(unresolvedConfig, source)) {
     info(
-      'The configuration file is not a simple object. Please refer to the migration guide for how to migrate it fully to Tailwind CSS v4. For now, we will load the configuration file as-is.',
+      'Your configuration file could not be automatically migrated to the new CSS configuration format, so your CSS has been updated to load your existing configuration file.',
     )
     return null
   }
@@ -63,8 +63,8 @@ async function migrateTheme(unresolvedConfig: Config & { theme: any }): Promise<
   let { extend: extendTheme, ...overwriteTheme } = unresolvedConfig.theme
 
   let resetNamespaces = new Map<string, boolean>()
-  // Before we merge the resetting theme values with the `extend` values, we
-  // capture all namespaces that need to be reset
+  // Before we merge theme overrides with theme extensions, we capture all
+  // namespaces that need to be reset.
   for (let [key, value] of themeableValues(overwriteTheme)) {
     if (typeof value !== 'string' && typeof value !== 'number') {
       continue
@@ -119,7 +119,7 @@ function createSectionKey(key: string[]): string {
   let sectionSegments = []
   for (let i = 0; i < key.length - 1; i++) {
     let segment = key[i]
-    // ignore tuples
+    // Ignore tuples
     if (key[i + 1][0] === '-') {
       break
     }
@@ -143,7 +143,7 @@ function migrateContent(
 }
 
 // Applies heuristics to determine if we can attempt to migrate the config
-function isSimpleConfig(unresolvedConfig: Config, source: string): boolean {
+function canMigrateConfig(unresolvedConfig: Config, source: string): boolean {
   // The file may not contain any functions
   if (source.includes('function') || source.includes(' => ')) {
     return false