-
Notifications
You must be signed in to change notification settings - Fork 628
Open
Labels
documentationImprovements or additions to documentation.Improvements or additions to documentation.t-toolingIssues with this label are in the ownership of the tooling team.Issues with this label are in the ownership of the tooling team.
Description
Current behavior
The API reference documentation currently categorizes class members into only two groups:
- Methods
- Properties
This is insufficient — all methods (instance, class, static, special) are lumped together, making it hard to navigate and understand the API surface of a class.
Proposed improvement
Categorize class members into more granular, meaningful groups.
Recommended groups (in this order)
- Special methods — dunder methods (
__init__,__repr__,__eq__,__iter__,__enter__,__exit__, etc.) that define object behavior - Properties —
@property,@cached_property(the API surface exposed as attributes) - Class methods —
@classmethod(factory methods, alternative constructors) - Static methods —
@staticmethod(utility functions related to the class) - Instance methods — regular methods working with
self(the bulk of the API)
Optional additional groups
- Abstract methods —
@abstractmethod(could be shown separately to highlight the contract) - Cached properties —
@cached_property(could be a sub-group of Properties)
Rationale
- Special methods at the top — they define how the object behaves (construction, representation, comparison, iteration, context management)
- Properties next — they are the primary API surface for attribute access
- Class/static methods — these are factory/helper methods
- Instance methods last — they form the bulk of the API and are the most numerous
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentation.Improvements or additions to documentation.t-toolingIssues with this label are in the ownership of the tooling team.Issues with this label are in the ownership of the tooling team.