Improve readmes for the new 1.4 checks

9 files changed, 30 insertions, 38 deletions

diff --git a/docs/checks/README-connect-by-name.md b/docs/checks/README-connect-by-name.md
index e5f7d255..bca17f0b 100644
--- a/docs/checks/README-connect-by-name.md
+++ b/docs/checks/README-connect-by-name.md
@@ -1,10 +1,8 @@
 # connect-by-name
 
-Warns when "auto-connection slots" are used. They're also known as "connect by name", a
-very old and unpopular feature which shouldn't be used anymore. See http://doc.qt.io/qt-5/qobject.html#auto-connection for more information about them.
+Warns when "auto-connection slots" are used. They're also known as "connect by name", an old and unpopular feature which isn't recommended. Consult the [official documentation](http://doc.qt.io/qt-5/qobject.html#auto-connection) for more information.
 
 These types of connections are very brittle, as a simple object rename would break your code.
-In Qt 5 the PMF connect syntax is recommended as it catches errors at compile time.
+In Qt 5 the *pointer-to-member-function* connect syntax is recommended as it catches errors at compile time.
 
-This check simply warns for any slot named like on_*_*, because even if you're not using .ui files
-this naming is misleading and not good for readability, as the reader would think you're using auto-connection.
+This check simply warns for any slot named like on_*_*, because even if you're not using .ui files this naming is misleading and not good for readability, as the reader would think you're using auto-connection.
diff --git a/docs/checks/README-fully-qualified-moc-types.md b/docs/checks/README-fully-qualified-moc-types.md
index 43f34055..408e6fbb 100644
--- a/docs/checks/README-fully-qualified-moc-types.md
+++ b/docs/checks/README-fully-qualified-moc-types.md
@@ -1,13 +1,12 @@
 # fully-qualified-moc-types
 
-Warns when a signal, slot or invokable declaration is not using fully-qualified type names, which will break old-style connects
-and interaction with QML.
+Warns when a signal, slot or invokable declaration is not using *fully-qualified* type names, which will break *old-style* connects and interaction with QML.
 
-Also warns if a Q_PROPERTY of type gadget is not fully-qualified (Enums and QObjects in Q_PROPERTY don't need
+Also warns if a `Q_PROPERTY` of type gadget is not fully-qualified (Enums and `QObject`s in `Q_PROPERTY` don't need
 to be fully qualified).
 
 Example:
-
+```
 namespace MyNameSpace {
 
     struct MyType { (...) };
@@ -21,6 +20,5 @@ namespace MyNameSpace {
         void mySignal(MyNameSpace::MyType); // OK
     };
 }
-
-Beware that fixing these type names might break user code if they are connecting to them via old style connects,
-since the users might have worked around your bug and not included the namespace in their connect statement
+```
+Beware that fixing these type names might break user code if they are connecting to them via *old-style* connects, since the users might have worked around your bug and not included the namespace in their connect statement.
diff --git a/docs/checks/README-qhash-with-char-pointer-key.md b/docs/checks/README-qhash-with-char-pointer-key.md
index 7d475105..483cd860 100644
--- a/docs/checks/README-qhash-with-char-pointer-key.md
+++ b/docs/checks/README-qhash-with-char-pointer-key.md
@@ -1,6 +1,5 @@
 # qhash-with-char-pointer-key
 
-Finds cases of `QHash<const char *, T>`. It's error-prone as the key is just compared
-by the address of the string literal, and not the string literal itself.
+Finds cases of `QHash<const char *, T>`. It's error-prone as the key is just compared by the address of the string literal and not the value itself.
 
-Check is disabled by default as there are valid uses-cases.
+This check is disabled by default as there are valid uses-cases.
diff --git a/docs/checks/README-qstring-varargs.md b/docs/checks/README-qstring-varargs.md
index aa029e46..8bfa6182 100644
--- a/docs/checks/README-qstring-varargs.md
+++ b/docs/checks/README-qstring-varargs.md
@@ -2,12 +2,10 @@
 
 This implements the equivalent of `-Wnon-pod-varargs` but only for `QString`.
 
-This check is disabled by default and is only useful in cases where you don't want
-to enable `-Wnon-pod-varargs`. For example on projects with thousands of benign warnings
-(like with CString), where you might only want to fix the `QString` cases.
-
-#### Example
-    QString s = (...)
-    LogError("error %s", s);
-
+This check is disabled by default and is only useful in cases where you don't want to enable `-Wnon-pod-varargs`. For example on projects with thousands of benign warnings (like with MFC's `CString`), where you might only want to fix the `QString` cases.
 
+Example
+```
+QString s = (...)
+LogError("error %s", s);
+```
diff --git a/docs/checks/README-qt-keywords.md b/docs/checks/README-qt-keywords.md
index 0abca20a..3aa1ae8d 100644
--- a/docs/checks/README-qt-keywords.md
+++ b/docs/checks/README-qt-keywords.md
@@ -1,12 +1,9 @@
 # qt-keywords
 
-Warns when using Qt keywords such as emit, slots, signals and foreach.
+Warns when using Qt keywords such as `emit`, `slots`, `signals` or `foreach`.
 
-This check is disabled by default and must be explicitly enabled, as using the
-above Qt keywords is fine unless you're using 3rdparty headers that also define them,
-in which case you'll want to use Q_EMIT, Q_SLOTS, Q_SIGNALS and Q_FOREACH instead.
+This check is disabled by default and must be explicitly enabled, since using the above Qt keywords is fine unless you're using 3rdparty headers that also define them, in which case you'll want to use `Q_EMIT`, `Q_SLOTS`, `Q_SIGNALS` or `Q_FOREACH` instead.
 
 It's also recommended you don't use the Qt keywords in public headers.
 
-Also consider using `CONFIG += no_keywords` (qmake) or `ADD_DEFINITIONS(-DQT_NO_KEYWORDS)` (CMake)
-instead of using this check.
+This check is mainly useful due to its *fixit* to automatically convert the keywords to their `Q_` variants. Once you've converted all usages, then simply enforce them via `CONFIG += no_keywords` (qmake) or `ADD_DEFINITIONS(-DQT_NO_KEYWORDS)` (CMake).
diff --git a/docs/checks/README-raw-environment-function.md b/docs/checks/README-raw-environment-function.md
index 265b02e9..b4ecf5bc 100644
--- a/docs/checks/README-raw-environment-function.md
+++ b/docs/checks/README-raw-environment-function.md
@@ -1,5 +1,5 @@
 # raw-environment-function
 
-Warns when `putenv()` or `qputenv()` are being used and suggests the Qt thread-safe equivalents instead.
+Warns when `putenv()` or `qputenv()` are being used and suggests the Qt *thread-safe* equivalents instead.
 
-This check is disabled by default and should be enabled manually if you worry about this issue.
+This check is disabled by default and should be enabled manually if *thread-safety* is an issue for you.
diff --git a/docs/checks/README-skipped-base-method.md b/docs/checks/README-skipped-base-method.md
index cf4a1bda..b2ad09fd 100644
--- a/docs/checks/README-skipped-base-method.md
+++ b/docs/checks/README-skipped-base-method.md
@@ -1,6 +1,6 @@
 # skipped-base-method
 
-Warns when calling a method from the "grand-base class" instead of the base-class method.
+Warns when calling a method from the "grand-base class" instead of the base-class one.
 
 Example:
 ```
diff --git a/docs/checks/README-static-pmf.md b/docs/checks/README-static-pmf.md
index e27e7b6c..39dbfedb 100644
--- a/docs/checks/README-static-pmf.md
+++ b/docs/checks/README-static-pmf.md
@@ -1,9 +1,10 @@
 # static-pmf
 
-Warns when storing a pointer to QObject member function into a static variable.
-Passing such variable to a connect is known to fail when using MingW.
+Warns when storing a pointer to `QObject` member function into a static variable and passing it to a connect statement.
+This is known to make the connect statement fail when the code is built with **MingW**.
 
 Example:
-
+```
 static auto pmf = &QObject::destroyed;
 QCOMPARE(pmf, &QObject::destroyed); // fails
+```
diff --git a/docs/checks/README-wrong-qevent-cast.md b/docs/checks/README-wrong-qevent-cast.md
index 96244231..3779bc82 100644
--- a/docs/checks/README-wrong-qevent-cast.md
+++ b/docs/checks/README-wrong-qevent-cast.md
@@ -1,11 +1,12 @@
 # wrong-qevent-cast
 
-Warns when a QEvent is possibly cast to the wrong derived class via static_cast.
+Warns when a `QEvent` is possibly cast to the wrong derived class via `static_cast`.
 
 Example:
+```
 switch (ev->type()) {
     case QEvent::MouseMove:
         auto e = static_cast<QKeyEvent*>(ev);
 }
-
-Currently only casts inside switches are verified.
+```
+Only casts inside switch statements are verified.