Skip to content

Improve API reference - categorize methods into meaningful groups #1779

@vdusek

Description

@vdusek

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)

  1. Special methods — dunder methods (__init__, __repr__, __eq__, __iter__, __enter__, __exit__, etc.) that define object behavior
  2. Properties@property, @cached_property (the API surface exposed as attributes)
  3. Class methods@classmethod (factory methods, alternative constructors)
  4. Static methods@staticmethod (utility functions related to the class)
  5. 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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation.t-toolingIssues with this label are in the ownership of the tooling team.

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions