Address comments

docs/index.md

@@ -373,8 +373,9 @@ print(Settings().model_dump())
 
 ### Disabling JSON parsing
 
-pydatnic-settings by default parses complex types from environment variables as JSON strings. If you want to disable
-this behavior for a field and parse the value by your own, you can annotate the field with `NoDecode`:
+pydantic-settings by default parses complex types from environment variables as JSON strings. If you want to disable
+this behavior for a field and parse the value in your own validator, you can annotate the field with
+[`NoDecode`](../api/pydantic_settings.md#pydantic_settings.NoDecode):
 
 ```py
 import os
@@ -430,13 +431,14 @@ print(Settings().model_dump())
 #> {'numbers': [1, 2, 3]}
 ```
 
-You can force JSON parsing for a field by annotating it with `ForceDecode`. This will bypass
-the the `enable_decoding` config setting:
+You can force JSON parsing for a field by annotating it with [`ForceDecode`](../api/pydantic_settings.md#pydantic_settings.ForceDecode).
+This will bypass the the `enable_decoding` config setting:
 
 ```py
 import os
 from typing import List
 
+from pydantic import field_validator
 from typing_extensions import Annotated
 
 from pydantic_settings import BaseSettings, ForceDecode, SettingsConfigDict
@@ -446,13 +448,23 @@ class Settings(BaseSettings):
     model_config = SettingsConfigDict(enable_decoding=False)
 
     numbers: Annotated[List[int], ForceDecode]
+    numbers1: List[int]  # (1)!
+
+    @field_validator('numbers1', mode='before')
+    @classmethod
+    def decode_numbers1(cls, v: str) -> List[int]:
+        return [int(x) for x in v.split(',')]
 
 
 os.environ['numbers'] = '["1","2","3"]'
+os.environ['numbers1'] = '1,2,3'
 print(Settings().model_dump())
-#> {'numbers': [1, 2, 3]}
+#> {'numbers': [1, 2, 3], 'numbers1': [1, 2, 3]}
 ```
 
+1. The `numbers1` field is not annotated with `ForceDecode`, so it will not be parsed as JSON.
+   and we have to provide a custom validator to parse the value.
+
 ## Nested model default partial updates
 
 By default, Pydantic settings does not allow partial updates to nested model default objects. This behavior can be

pydantic_settings/sources.py

@@ -119,10 +119,14 @@ def import_azure_key_vault() -> None:
 
 
 class NoDecode:
+    """Annotation to prevent decoding of a field value."""
+
     pass
 
 
 class ForceDecode:
+    """Annotation to force decoding of a field value."""
+
     pass