Skip to content

Updating and improving clarity in help documentation for clean subcommands#2179

Merged
ChrisLovering merged 3 commits into
python-discord:mainfrom
Autonymic:docs/clean-help
May 31, 2022
Merged

Updating and improving clarity in help documentation for clean subcommands#2179
ChrisLovering merged 3 commits into
python-discord:mainfrom
Autonymic:docs/clean-help

Conversation

@Autonymic
Copy link
Copy Markdown
Contributor

@Autonymic Autonymic commented May 22, 2022

This should close #2170.

I have removed the obsolete description about the traverse argument in the clean bots subcommand and fixed as well as added to the description of the clean regex subcommand.

I also improved the explanations for the message or timelimit argument and their relation to the channel argument across all clean subcommands.

Copy link
Copy Markdown
Contributor

@wookie184 wookie184 left a comment

Choose a reason for hiding this comment

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

Thanks for doing this, I just have one comment.

Comment thread bot/exts/moderation/clean.py Outdated
Comment on lines +546 to +554
The `regex` pattern must be provided enclosed in backticks, that will make it appear as a code section.

For example: \u02CB[0-9]\u02CB, which should appear as `[0-9]`.

If the `regex` pattern contains spaces, it still needs to be enclosed in double quotes on top of that.

For example: "\u02CB[0-9]\u02CB", which should appear as "`[0-9]`".

Do not copy and paste the backticks from the examples, they are special unicode characters that will not work.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think this bit is a bit wordier than it needs to be, I think something like this would suffice (note backticks can be escaped with \):

        The `regex` pattern must be enclosed in backticks (e.g. \`[0-9]\`). 
        If it contains a space it must also be enclosed in double quotes (e.g. "\`test [0-9]\`").

image

I'm not exactly sure what change the original issue was proposing to this part though. Thoughts?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The problem is that the intent seems to be to show how to write the regex part of the command, e.g. must be enclosed in backticks [0-9], but the problem is when it appears on discord it just turns into a code block due to the [0-9] being enclosed in ``, potentially making a less knowledgeable user confused.

When I tried escaping the standard backticks with backslash the linter didn't seem to like it, so I just chose to use special unicode characters that won't turn into a code block, even though it may cause confusion if a user tries to copypaste those backticks.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Ah, in that case you can escape the backticks explicitly to make the linter happy

        The `regex` pattern must be enclosed in backticks (e.g. \\`[0-9]\\`).
        If it contains a space it must also be enclosed in double quotes (e.g. "\\`test [0-9]\\`").

(is the same as my screenshot above)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yeah that seemed to do the trick, thanks! I removed some of the excessive words, so it should be a bit cleaner now.

@Xithrius Xithrius added a: docs Adds or updates documentation p: 3 - low Low Priority s: waiting for author Waiting for author to address a review or respond to a comment t: enhancement Changes or improvements to existing features labels May 27, 2022
Copy link
Copy Markdown
Contributor

@wookie184 wookie184 left a comment

Choose a reason for hiding this comment

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

Looks good, thanks.

Copy link
Copy Markdown
Member

@ChrisLovering ChrisLovering left a comment

Choose a reason for hiding this comment

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

Looks good, thanks :)

@ChrisLovering ChrisLovering merged commit 80a5b83 into python-discord:main May 31, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

a: docs Adds or updates documentation p: 3 - low Low Priority s: waiting for author Waiting for author to address a review or respond to a comment t: enhancement Changes or improvements to existing features

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve help text of the !clean subcommands

4 participants