better comments

Author: ikusakov

website/src/pages/docs/migration/apollo-tooling.mdx

@@ -284,7 +284,7 @@ import type { CodegenConfig } from '@graphql-codegen/cli'
 const config: CodegenConfig = {
   schema: './schema.graphql',
   documents: ['./src/**/*.{ts,tsx}', '!./src/**/__generated__/**'],
-  // `externalDocuments` are read-only documents that are loaded but do not generate any output.
+  // `externalDocuments` are read-only documents that are loaded but do not generate output.
   // They are used to include fragments from another package within a monorepo.
   externalDocuments: ['../other-package/src/**/*.{ts,tsx}', '!../other-package/src/**/__generated__/**'],
   generates: {
@@ -330,17 +330,17 @@ export default config
 The setup above closely mimics Apollo Tooling but isn’t an exact match. The following items may
 require manual fixes:
 
-1. Nested field types naming.
+#### 1. Nested field types naming.
 
 In very rare cases, the field names generated by GraphQL Codegen don’t match Apollo Tooling’s. Update
 these cases manually.
 
-2. Enum file location.
+#### 2. Enum file location.
 
 Occasionally, GraphQL Codegen places enums in a different file then Apollo Tooling. If an enum is
 missing, check nearby generated files and adjust your imports accordingly.
 
-3. `is possibly null` and `has any type` typecheck bugs.
+#### 3. `is possibly null` and `has any type` typecheck bugs.
 
 These bugs has to be fixed.
 
@@ -352,30 +352,26 @@ For `is possibly null` bug, asserting for not null or adding `!` will fix most c
 
 For `has any type` bug - a proper type needs to be determined.
 
-4. Mismatch between `Type | null` and `Type | null | undefined`.
+#### 4. Mismatch between `Type | null` and `Type | null | undefined`.
 
 Experiment with the following configuration options to keep your codebase changes to a minimum:
 
-```
-  maybeValue: defaults to 'T | null', set to 'T | null | undefined' if necessary
-  inputMaybeValue: defaults to 'Maybe<T>', set to 'T | null | undefined' if necessary
-  avoidOptionals: Replaces ? optional modifier with explicit Maybe<T>. Supports granular control via object form.
-  allowUndefinedQueryVariables: Adds | undefined to Query operation variable types (not Mutation/Subscription)
-  optionalResolveType: Makes __resolveType optional (__resolveType?) in resolver types.
-  nullability:  When errorHandlingClient: true, adjusts nullability for fields marked with @semanticNonNull directive (requires graphql-sock).
-```
+* **maybeValue**: defaults to `T | null`, set to `T | null | undefined` if necessary
+* **inputMaybeValue**: defaults to `Maybe<T>`, set to `T | null | undefined` if necessary
+* **avoidOptionals**: Replaces ? optional modifier with explicit `Maybe<T>`. Supports granular control via object form.
+* **allowUndefinedQueryVariables**: Adds | undefined to Query operation variable types (not Mutation/Subscription)
+* **optionalResolveType**: Makes `__resolveType` optional (`__resolveType?`) in resolver types.
+* **nullability**:  When `errorHandlingClient: true`, adjusts nullability for fields marked with `@semanticNonNull` directive (requires `graphql-sock`).
 
-5. Extra `__typename` present, or required `__typename` missing.
+#### 5. Extra `__typename` present, or required `__typename` missing.
 
 Experiment with the following configuration options to keep your codebase changes to a minimum:
 
-```
-  skipTypename: prevents adding __typename to generated types unless explicitly in the selection set.
-  skipTypeNameForRoot: skips __typename specifically for root types (Query, Mutation, Subscription). Ignored if __typename is explicitly in the selection set
-  nonOptionalTypename: always adds __typename and makes it a required (non-optional) field.
-  addTypenameToSelectionSets: injects __typename directly into the generated document node selection sets.
-  resolversNonOptionalTypename: makes __typename non-optional in resolver mappings without affecting base types. Supports granular control via object form.
-```
+* **skipTypename**: prevents adding `__typename` to generated types unless explicitly in the selection set.
+* **skipTypeNameForRoot**: skips `__typename` specifically for root types (Query, Mutation, Subscription). Ignored if `__typename` is explicitly in the selection set
+* **nonOptionalTypename**: always adds `__typename` and makes it a required (non-optional) field.
+* **addTypenameToSelectionSets**: injects `__typename` directly into the generated document node selection sets.
+* **resolversNonOptionalTypename**: makes `__typename` non-optional in resolver mappings without affecting base types. Supports granular control via object form.
 
 ## Further reading