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
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions