From fe8aa33980b16adcf4ee352930f424db151ec5ed Mon Sep 17 00:00:00 2001 From: pajlada Date: Sat, 21 Aug 2021 14:41:06 +0200 Subject: [PATCH] Update Usage messages to conform to new Usage message contributor guidelines (#3180) --- CONTRIBUTING.md | 25 +++++++++++++++++++ .../commands/CommandController.cpp | 16 ++++++------ src/providers/twitch/IrcMessageHandler.cpp | 3 +-- 3 files changed, 34 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7135e908b..094d60bb4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -215,3 +215,28 @@ Keep the element on the stack if possible. If you need a pointer or have complex - Use the [object tree](https://doc.qt.io/qt-5/objecttrees.html#) to manage lifetimes where possible. Objects are destroyed when their parent object is destroyed. - If you have to explicitly delete an object use `variable->deleteLater()` instead of `delete variable`. This ensures that it will be deleted on the correct thread. - If an object doesn't have a parent, consider using `std::unique_ptr` with `DeleteLater` from "src/common/Common.hpp". This will call `deleteLater()` on the pointer once it goes out of scope, or the object is destroyed. + +## Conventions + +#### Usage strings + +When informing the user about how a command is supposed to be used, we aim to follow [this standard](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html) where possible. + +- Square brackets are reserved for `[optional arguments]`. +- Angle brackets are reserved for ``. +- The word _Usage_ should be capitalized and must be followed by a colon. +- If the usage deserves a description, put a dot after all parameters and explain it briefly. + +##### Good + +- `Usage: /block ` +- `Usage: /unblock . Unblocks a user.` +- `Usage: /streamlink ` +- `Usage: /usercard [channel]` + +##### Bad + +- `Usage /streamlink ` - Missing colon after _Usage_. +- `usage: /streamlink ` - _Usage_ must be capitalized. +- `Usage: /streamlink channel` - The required argument `channel` must be wrapped in angle brackets. +- `Usage: /streamlink .` - Don't put a dot after usage if it's not followed by a description. diff --git a/src/controllers/commands/CommandController.cpp b/src/controllers/commands/CommandController.cpp index 1ca76023f..82beac036 100644 --- a/src/controllers/commands/CommandController.cpp +++ b/src/controllers/commands/CommandController.cpp @@ -296,7 +296,7 @@ void CommandController::initialize(Settings &, Paths &paths) auto blockLambda = [](const auto &words, auto channel) { if (words.size() < 2) { - channel->addMessage(makeSystemMessage("Usage: /block [user]")); + channel->addMessage(makeSystemMessage("Usage: /block ")); return ""; } @@ -341,7 +341,7 @@ void CommandController::initialize(Settings &, Paths &paths) auto unblockLambda = [](const auto &words, auto channel) { if (words.size() < 2) { - channel->addMessage(makeSystemMessage("Usage: /unblock [user]")); + channel->addMessage(makeSystemMessage("Usage: /unblock ")); return ""; } @@ -455,7 +455,7 @@ void CommandController::initialize(Settings &, Paths &paths) if (words.size() < 2) { channel->addMessage( - makeSystemMessage("Usage /user [user] (channel)")); + makeSystemMessage("Usage: /user [channel]")); return ""; } QString userName = words[1]; @@ -625,7 +625,7 @@ void CommandController::initialize(Settings &, Paths &paths) (!channel->isTwitchChannel() || channel->isEmpty())) { channel->addMessage(makeSystemMessage( - "Usage: /streamlink [channel]. You can also use the " + "Usage: /streamlink . You can also use the " "command without arguments in any Twitch channel to open " "it in streamlink.")); return ""; @@ -646,7 +646,7 @@ void CommandController::initialize(Settings &, Paths &paths) (!channel->isTwitchChannel() || channel->isEmpty())) { channel->addMessage(makeSystemMessage( - "Usage: /popout [channel]. You can also use the command " + "Usage: /popout . You can also use the command " "without arguments in any Twitch channel to open its " "popout chat.")); return ""; @@ -673,7 +673,7 @@ void CommandController::initialize(Settings &, Paths &paths) if (words.size() < 2) { channel->addMessage( - makeSystemMessage("Usage: /settitle .")); + makeSystemMessage("Usage: /settitle ")); return ""; } if (auto twitchChannel = dynamic_cast(channel.get())) @@ -704,7 +704,7 @@ void CommandController::initialize(Settings &, Paths &paths) if (words.size() < 2) { channel->addMessage( - makeSystemMessage("Usage: /setgame .")); + makeSystemMessage("Usage: /setgame ")); return ""; } if (auto twitchChannel = dynamic_cast(channel.get())) @@ -769,7 +769,7 @@ void CommandController::initialize(Settings &, Paths &paths) const ChannelPtr channel) { if (words.size() < 2) { - channel->addMessage(makeSystemMessage("Usage: /openurl .")); + channel->addMessage(makeSystemMessage("Usage: /openurl ")); return ""; } diff --git a/src/providers/twitch/IrcMessageHandler.cpp b/src/providers/twitch/IrcMessageHandler.cpp index a4ce3c513..e15362a5e 100644 --- a/src/providers/twitch/IrcMessageHandler.cpp +++ b/src/providers/twitch/IrcMessageHandler.cpp @@ -810,8 +810,7 @@ void IrcMessageHandler::handleNoticeMessage(Communi::IrcNoticeMessage *message) if (tags == "bad_delete_message_error" || tags == "usage_delete") { channel->addMessage(makeSystemMessage( - "Usage: \"/delete \" - can't take more " - "than one argument")); + "Usage: /delete . Can't take more than one argument")); } else if (tags == "host_on" || tags == "host_target_went_offline") {