Migrate attribute comments to docstrings (#3639)

* Migrate attribute comments to docstrings

* Minor fixes

* Update AGENTS.md

* Remove leading enwlines

Author: r4victor

AGENTS.md

@@ -20,6 +20,7 @@
 - Keep primary/public functions before local helper functions in a module section.
 - Keep private classes, exceptions, and similar implementation-specific types close to the private functions that use them unless they are shared more broadly in the module.
 - Prefer pydantic-style models in `core/models`.
+- Document attributes when the note adds behavior, compatibility, or semantic context that is not obvious from the name and type. Use attribute docstrings without leading newline.
 - Tests use `test_*.py` modules and `test_*` functions; fixtures live near usage.
 
 ## Testing Guidelines

src/dstack/_internal/core/models/backends/base.py

@@ -32,15 +32,16 @@ class BackendType(str, enum.Enum):
     CLOUDRIFT = "cloudrift"
     CRUSOE = "crusoe"
     CUDO = "cudo"
-    DATACRUNCH = "datacrunch"  # BackendType for backward compatibility
+    DATACRUNCH = "datacrunch"
+    """`DATACRUNCH` is kept as a `BackendType` for backward compatibility."""
     DIGITALOCEAN = "digitalocean"
     DSTACK = "dstack"
     GCP = "gcp"
     HOTAISLE = "hotaisle"
     KUBERNETES = "kubernetes"
     LAMBDA = "lambda"
     LOCAL = "local"
-    REMOTE = "remote"  # TODO: replace for LOCAL
+    REMOTE = "remote"
     NEBIUS = "nebius"
     OCI = "oci"
     RUNPOD = "runpod"

src/dstack/_internal/core/models/common.py

@@ -134,8 +134,10 @@ class RegistryAuth(FrozenCoreModel):
 
 
 class ApplyAction(str, Enum):
-    CREATE = "create"  # resource is to be created or overridden
-    UPDATE = "update"  # resource is to be updated in-place
+    CREATE = "create"
+    """`CREATE` means the resource is to be created or overridden."""
+    UPDATE = "update"
+    """`UPDATE` means the resource is to be updated in-place."""
 
 
 class NetworkMode(str, Enum):

src/dstack/_internal/core/models/compute_groups.py

@@ -24,12 +24,14 @@ class ComputeGroupProvisioningData(CoreModel):
     compute_group_id: str
     compute_group_name: str
     backend: BackendType
-    # In case backend provisions instance in another backend,
-    # it may set that backend as base_backend.
     base_backend: Optional[BackendType] = None
+    """`base_backend` may be set when a backend provisions an instance in another backend and needs
+    to record that backend as `base_backend`.
+    """
     region: str
     job_provisioning_datas: List[JobProvisioningData]
-    backend_data: Optional[str] = None  # backend-specific data in json
+    backend_data: Optional[str] = None
+    """`backend_data` stores backend-specific data in JSON."""
 
 
 class ComputeGroup(CoreModel):

src/dstack/_internal/core/models/config.py

@@ -23,6 +23,7 @@ class RepoConfig(CoreModel):
 
 class GlobalConfig(CoreModel):
     projects: Annotated[List[ProjectConfig], Field(description="The list of projects")] = []
-    # Not used since 0.20.0. Can be removed when most users update their `config.yml` (it's updated
-    # each time a project is added)
     repos: Annotated[list[RepoConfig], Field(exclude=True)] = []
+    """`repos` is not used since 0.20.0. It can be removed when most users update their `config.yml`
+    because it is updated each time a project is added.
+    """

src/dstack/_internal/core/models/configurations.py

@@ -101,10 +101,10 @@ def parse(cls, v: str) -> "PortMapping":
 
 
 class RepoExistsAction(str, Enum):
-    # Don't try to check out, terminate the run with an error (the default action since 0.20.0)
     ERROR = "error"
-    # Don't try to check out, skip the repo (the logic hardcoded in the pre-0.20.0 runner)
+    """`ERROR` means do not try to check out and terminate the run with an error. This is the default action since 0.20.0."""
     SKIP = "skip"
+    """`SKIP` means do not try to check out and skip the repo. This is the logic hardcoded in the pre-0.20.0 runner."""
 
 
 class RepoSpec(CoreModel):
@@ -469,8 +469,8 @@ class BaseRunConfiguration(CoreModel):
             ),
         ),
     ] = None
-    # deprecated since 0.18.31; has no effect
     home_dir: str = "/root"
+    """`home_dir` is deprecated since 0.18.31 and has no effect."""
     registry_auth: Annotated[
         Optional[RegistryAuth], Field(description="Credentials for pulling a private Docker image")
     ] = None
@@ -540,8 +540,11 @@ class BaseRunConfiguration(CoreModel):
         list[FilePathMapping],
         Field(description="The local to container file path mappings"),
     ] = []
-    # deprecated since 0.18.31; task, service -- no effect; dev-environment -- executed right before `init`
     setup: CommandsList = []
+    """
+    setup: Deprecated since 0.18.31. It has no effect for tasks and services; for
+    dev environments it runs right before `init`.
+    """
 
     @validator("python", pre=True, always=True)
     def convert_python(cls, v, values) -> Optional[PythonVersion]:

src/dstack/_internal/core/models/fleets.py

@@ -30,8 +30,8 @@
 
 
 class FleetStatus(str, Enum):
-    # Currently all fleets are ACTIVE/TERMINATING/TERMINATED
-    # SUBMITTED/FAILED may be used if fleets require async processing
+    # Currently all fleets are ACTIVE, TERMINATING, or TERMINATED.
+    # SUBMITTED and FAILED may be used if fleets require async processing.
     SUBMITTED = "submitted"
     ACTIVE = "active"
     TERMINATING = "terminating"
@@ -372,10 +372,11 @@ class FleetSpec(generate_dual_core_model(FleetSpecConfig)):
     configuration_path: Optional[str] = None
     profile: Profile
     autocreated: bool = False
-    # merged_profile stores profile parameters merged from profile and configuration.
-    # Read profile parameters from merged_profile instead of profile directly.
-    # TODO: make merged_profile a computed field after migrating to pydanticV2
+    # TODO: make `merged_profile` a computed field after migrating to Pydantic v2.
     merged_profile: Annotated[Profile, Field(exclude=True)] = None
+    """`merged_profile` stores profile parameters merged from `profile` and `configuration`.
+    Read profile parameters from `merged_profile` instead of `profile` directly.
+    """
 
     @root_validator
     def _merged_profile(cls, values) -> Dict:
@@ -416,7 +417,8 @@ class FleetPlan(CoreModel):
     offers: List[InstanceOfferWithAvailability]
     total_offers: int
     max_offer_price: Optional[float] = None
-    action: Optional[ApplyAction] = None  # default value for backward compatibility
+    action: Optional[ApplyAction] = None
+    """`action` uses a default value for backward compatibility."""
 
     def get_effective_spec(self) -> FleetSpec:
         if self.effective_spec is not None:

src/dstack/_internal/core/models/gateways.py

@@ -102,27 +102,33 @@ class GatewaySpec(CoreModel):
 
 
 class Gateway(CoreModel):
-    # ID is only optional on the client side for compatibility with pre-0.20.7 servers.
-    # TODO(0.21): Make required.
+    # TODO(0.21): Make `id` required.
     id: Optional[uuid.UUID] = None
+    """`id` is only optional on the client side for compatibility with pre-0.20.7 servers."""
     name: str
     configuration: GatewayConfiguration
     created_at: datetime.datetime
     status: GatewayStatus
     status_message: Optional[str]
-    # The ip address / hostname the user should set up the domain for.
-    # Could be the same as ip_address but also different, e.g. gateway behind ALB.
     hostname: Optional[str]
-    # The ip address of the gateway instance
+    """`hostname` is the IP address or hostname the user should set up the domain for.
+    Could be the same as `ip_address` but also different, for example a gateway behind ALB.
+    """
     ip_address: Optional[str]
+    """`ip_address` is the IP address of the gateway instance."""
     instance_id: Optional[str]
     wildcard_domain: Optional[str]
     default: bool
-    # TODO: Deprecated configuration fields duplicated on top-level
-    # for backward compatibility with 0.19.x clients that expect them required.
-    # Remove after 0.21
     backend: Optional[BackendType] = None
+    """`backend` duplicates a configuration field on the top level for backward compatibility
+    with 0.19.x clients that expect it to be required.
+    Remove after 0.21.
+    """
     region: Optional[str] = None
+    """`region` duplicates a configuration field on the top level for backward compatibility
+    with 0.19.x clients that expect it to be required.
+    Remove after 0.21.
+    """
 
 
 class GatewayPlan(CoreModel):
@@ -147,8 +153,10 @@ class GatewayComputeConfiguration(CoreModel):
 
 class GatewayProvisioningData(CoreModel):
     instance_id: str
-    ip_address: str  # TODO: rename, Kubernetes uses domain names
+    # TODO: rename `ip_address`; Kubernetes uses domain names here.
+    ip_address: str
     region: str
     availability_zone: Optional[str] = None
     hostname: Optional[str] = None
-    backend_data: Optional[str] = None  # backend-specific data in json
+    backend_data: Optional[str] = None
+    """`backend_data` stores backend-specific data in JSON."""

src/dstack/_internal/core/models/instances.py

@@ -23,9 +23,10 @@
 class Gpu(CoreModel):
     name: str
     memory_mib: int
-    # Although it's declared as Optional, in fact it always has a value set by the root validator,
-    # that is, `assert gpu.vendor is not None` should be a safe type narrowing.
     vendor: Optional[gpuhunt.AcceleratorVendor] = None
+    """`vendor` is declared as optional, but the root validator always sets a value.
+    `assert gpu.vendor is not None` should be a safe type narrowing.
+    """
 
     @root_validator(pre=True)
     def validate_name_and_vendor(cls, values):
@@ -54,13 +55,15 @@ class Resources(CoreModel):
     memory_mib: int
     gpus: List[Gpu]
     spot: bool
-    disk: Disk = Disk(size_mib=102400)  # the default value (100GB) for backward compatibility
+    disk: Disk = Disk(size_mib=102400)
+    """`disk` defaults to 100GB for backward compatibility."""
     cpu_arch: Optional[gpuhunt.CPUArchitecture] = None
-    # Deprecated: description is now generated client-side. TODO: remove in 0.21.
+    # TODO: remove `description` in 0.21.
     description: Annotated[
         str,
         Field(description="Deprecated: generated client-side. Will be removed in 0.21."),
     ] = ""
+    """`description` is deprecated because it is now generated client-side."""
 
     @root_validator
     def _description(cls, values) -> Dict:
@@ -187,7 +190,8 @@ class RemoteConnectionInfo(CoreModel):
 class InstanceConfiguration(CoreModel):
     project_name: str
     instance_name: str
-    user: str  # dstack user name
+    user: str
+    """`user` stores the dstack user name."""
     ssh_keys: List[SSHKey]
     instance_id: Optional[str] = None
     reservation: Optional[str] = None
@@ -208,7 +212,8 @@ class InstanceAvailability(Enum):
     AVAILABLE = "available"
     NOT_AVAILABLE = "not_available"
     NO_QUOTA = "no_quota"
-    NO_BALANCE = "no_balance"  # For dstack Sky
+    NO_BALANCE = "no_balance"
+    """`NO_BALANCE` is used for dstack Sky."""
     IDLE = "idle"
     BUSY = "busy"
 
@@ -268,7 +273,8 @@ class InstanceTerminationReason(str, Enum):
     NO_OFFERS = "no_offers"
     MASTER_FAILED = "master_failed"
     MAX_INSTANCES_LIMIT = "max_instances_limit"
-    NO_BALANCE = "no_balance"  # used in dstack Sky
+    NO_BALANCE = "no_balance"
+    """`NO_BALANCE` is used in dstack Sky."""
 
     @classmethod
     def from_legacy_str(cls, v: str) -> "InstanceTerminationReason":
@@ -332,14 +338,16 @@ class Instance(CoreModel):
     fleet_id: Optional[UUID] = None
     fleet_name: Optional[str] = None
     instance_num: int
-    job_name: Optional[str] = None  # deprecated, always None (instance can have more than one job)
+    job_name: Optional[str] = None
+    """`job_name` is deprecated and always `None` because an instance can have more than one job."""
     hostname: Optional[str] = None
     status: InstanceStatus
     unreachable: bool = False
     health_status: HealthStatus = HealthStatus.HEALTHY
-    # termination_reason stores InstanceTerminationReason.
-    # str allows adding new enum members without breaking compatibility with old clients.
     termination_reason: Optional[str] = None
+    """`termination_reason` stores `InstanceTerminationReason`.
+    `str` allows adding new enum members without breaking compatibility with old clients.
+    """
     termination_reason_message: Optional[str] = None
     created: datetime.datetime
     finished_at: Optional[datetime.datetime] = None

src/dstack/_internal/core/models/placement.py

@@ -16,7 +16,8 @@ class PlacementGroupConfiguration(CoreModel):
 
 
 class PlacementGroupProvisioningData(CoreModel):
-    backend: BackendType  # can be different from configuration backend
+    backend: BackendType
+    """`backend` can be different from the backend in `configuration`."""
     backend_data: Optional[str] = None