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.

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

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

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions discord/ui/item.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.


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.
Comment on lines +105 to +106
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 04 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.


Raises
------
ValueError
If set to a value less than 0 or greater than or equal to 5.
"""
return self._row

@row.setter
Expand All @@ -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.


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?


Returns
-------
:class:`int`
The width of the item, defaulting to 1.
Comment on lines +131 to +134
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.

"""
return 1

@property
Expand Down