Skip to content

Migrate Python attribute comments to attribute docstrings #3638

@r4victor

Description

@r4victor

For historical reasons, dstack Python codebase uses comments before attributes to document the attributes (unless there is a more appropriate place like Field(description="...")). These comments have no special meaning to Python tooling, are not recognized by the IDEs, so you don't see any help when hover over an attribute in IDE.

Python has “attribute docstrings” convention as described in PEP 257:

String literals occurring immediately after a simple assignment at the top level of a module, class, or init method are called “attribute docstrings”.

These are recognized by Python tooling and the descriptions are visible in IDEs. Compare docstrings vs comments:

Image Image

I suggest we migrate all comments attribute descriptions to attribute docstrings. There is a readability difference in that docstrings go after the attribute but that's Python tooling convention and we won't change it now.

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions