Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add detailed docstrings for row and width properties in the Item class #10057

Closed
wants to merge 3 commits into from
Closed

Add detailed docstrings for row and width properties in the Item class #10057

wants to merge 3 commits into from

Conversation

Error44s
Copy link

@Error44s Error44s commented Dec 28, 2024 •
edited
Loading

Summary

This pull request adds detailed docstrings to the row and width properties of the Item class in the Discord.py library. These docstrings provide clear explanations of their purpose, valid values, constraints, and usage within the framework, improving overall code clarity and documentation.

Checklist

  • If code changes were made then they have been tested.
    • I have updated the documentation to reflect the changes.
  • This PR fixes an issue.
  • This PR adds something new (e.g. new method or parameters).
  • This PR is a breaking change (e.g. methods or parameters removed/renamed).
  • This PR is not a code change (e.g. documentation, README, ...).

owocado
owocado suggested changes Jan 10, 2025
View reviewed changes
discord/ui/item.py
@@ -113,6 +123,16 @@ def row(self, value: Optional[int]) -> None:

@property
def width(self) -> int:
"""int: The width of this item in a Discord UI layout.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"""int: The width of this item in a Discord UI layout.
""":class:`int`: Returns the width of this item in a Discord UI layout.

discord/ui/item.py
@@ -100,6 +100,16 @@ def __repr__(self) -> str:

@property
def row(self) -> Optional[int]:
"""Optional[:class:`int`]: The action row this item belongs to.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"""Optional[:class:`int`]: The action row this item belongs to.
"""Optional[:class:`int`]: Returns the action row this item belongs to.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"""Optional[:class:`int`]: The action row this item belongs to.
"""Optional[:class:`int`]: Returns the row this item belongs to.

DA-344
DA-344 reviewed Jan 14, 2025
View reviewed changes
discord/ui/item.py
Comment on lines +131 to +134
Returns
-------
:class:`int`
The width of the item, defaulting to 1.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Returns
-------
:class:`int`
The width of the item, defaulting to 1.

Properties don't have this Return, as their return type are stated above.

discord/ui/item.py
Comment on lines +105 to +106
An action row can have up to 5 components. Valid values for the row are
integers in the range 0–4 or ``None`` to indicate no specific row.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
An action row can have up to 5 components. Valid values for the row are
integers in the range 0–4 or ``None`` to indicate no specific row.

This is already documented on the row parameter on each different Item subclass, so it is not needed.

discord/ui/item.py
@@ -100,6 +100,16 @@ def __repr__(self) -> str:

@property
def row(self) -> Optional[int]:
"""Optional[:class:`int`]: The action row this item belongs to.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"""Optional[:class:`int`]: The action row this item belongs to.
"""Optional[:class:`int`]: Returns the row this item belongs to.

discord/ui/item.py
"""int: The width of this item in a Discord UI layout.

The width determines how much space this item occupies in an action row.
This value is primarily used internally by Discord.py to calculate layout constraints.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think mentioning this is necessary?

@Rapptz
Copy link
Owner

Rapptz commented Jan 15, 2025

These are not documented on purpose since they're not part of public API.

width is there for internal reasons when calculating stuff, and row is there as an API convenience not meant to be relied upon. In the future they might even go away with changes to the component infrastructure so codifying it further than it already is (such as row in the constructors and decorators) is only going to cause more struggles.

Thanks for the PR though.

@Rapptz Rapptz closed this Jan 15, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@DA-344 DA-344 DA-344 left review comments

@owocado owocado owocado requested changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@Error44s @Rapptz @owocado @DA-344