Docs update: keeping model_fields_set defs consistent and adding expl…

…anation for model_rebuild changes (#7818)

docs/concepts/models.md

@@ -204,6 +204,10 @@ print(Foo.model_json_schema())
 Pydantic tries to determine when this is necessary automatically and error if it wasn't done, but you may want to
 call `model_rebuild()` proactively when dealing with recursive models or generics.
 
+In V2, `model_rebuild()` replaced `update_forward_refs()` from V1. There are some slight differences with the new behavior.
+The biggest change is that when calling `model_rebuild` on the outermost model, it builds a core schema used for validation of the
+whole model (nested models and all), so all types at all levels need to be ready before `model_rebuild` is called.
+
 ## Arbitrary class instances
 
 (Formerly known as "ORM Mode"/`from_orm`.)

docs/migration.md

@@ -92,6 +92,7 @@ to help ease migration, but calling them will emit `DeprecationWarning`s.
 | `json_schema()` | `model_json_schema()` |
 | `json()` | `model_dump_json()` |
 | `parse_obj()` | `model_validate()` |
+| `update_forward_refs()` | `model_rebuild()` |
 
 * Some of the built-in data-loading functionality has been slated for removal. In particular,
     `parse_raw` and `parse_file` are now deprecated. In Pydantic V2, `model_validate_json` works like `parse_raw`. Otherwise, you should load the data and then pass it to `model_validate`.
@@ -128,7 +129,8 @@ to help ease migration, but calling them will emit `DeprecationWarning`s.
   section of the model exporting docs.
 * `GetterDict` has been removed as it was just an implementation detail of `orm_mode`, which has been removed.
 * In many cases, arguments passed to the constructor will be copied in order to perform validation and, where necessary, coercion.
-  This is notable in the case of passing mutable objects as arguments to a constructor. You can see an example + more detail [here](https://docs.pydantic.dev/latest/concepts/models/#attribute-copies).
+  This is notable in the case of passing mutable objects as arguments to a constructor.
+  You can see an example + more detail [here](https://docs.pydantic.dev/latest/concepts/models/#attribute-copies).
 
 ### Changes to `pydantic.generics.GenericModel`
 

pydantic/main.py

@@ -82,7 +82,7 @@ class BaseModel(metaclass=_model_construction.ModelMetaclass):
 
         __pydantic_extra__: An instance attribute with the values of extra fields from validation when
             `model_config['extra'] == 'allow'`.
-        __pydantic_fields_set__: An instance attribute with the names of fields explicitly specified during validation.
+        __pydantic_fields_set__: An instance attribute with the names of fields explicitly set.
         __pydantic_private__: Instance attribute with the values of private attributes set on the model instance.
     """
 
@@ -186,7 +186,7 @@ def model_extra(self) -> dict[str, Any] | None:
 
     @property
     def model_fields_set(self) -> set[str]:
-        """Returns the set of fields that have been set on this model instance.
+        """Returns the set of fields that have been explicitly set on this model instance.
 
         Returns:
             A set of strings representing the fields that have been set,
@@ -296,7 +296,7 @@ def model_dump(
             include: A list of fields to include in the output.
             exclude: A list of fields to exclude from the output.
             by_alias: Whether to use the field's alias in the dictionary key if defined.
-            exclude_unset: Whether to exclude fields that are unset or None from the output.
+            exclude_unset: Whether to exclude fields that have not been explicitly set.
             exclude_defaults: Whether to exclude fields that are set to their default value from the output.
             exclude_none: Whether to exclude fields that have a value of `None` from the output.
             round_trip: Whether to enable serialization and deserialization round-trip support.