Update Usage messages to conform to new Usage message contributor guidelines (#3180)

2021-08-21 14:41:06 +02:00
parent ad4a0c28d1
commit fe8aa33980
3 changed files with 34 additions and 10 deletions
@@ -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<Type, DeleteLater>` 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 `<required arguments>`.
+- 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 <user>`
+- `Usage: /unblock <user>. Unblocks a user.`
+- `Usage: /streamlink <channel>`
+- `Usage: /usercard <user> [channel]`
+
+##### Bad
+
+- `Usage /streamlink <channel>` - Missing colon after _Usage_.
+- `usage: /streamlink <channel>` - _Usage_ must be capitalized.
+- `Usage: /streamlink channel` - The required argument `channel` must be wrapped in angle brackets.
+- `Usage: /streamlink <channel>.` - Don't put a dot after usage if it's not followed by a description.