diff --git a/doc/help/kdb-validate.md b/doc/help/kdb-validate.md
index 87745c308c4..fc4bf811d83 100644
--- a/doc/help/kdb-validate.md
+++ b/doc/help/kdb-validate.md
@@ -14,19 +14,19 @@ their specifications.
 For keys to be validated, they must contain the 'check'-metakeys
 and the respective plugins for validation must be loaded
 for the backend that was used while mounting.
-If a validation is done while using 'kdb set'
-the same validation is also done by 'kdb validate'
+If a validation is done while using `kdb set` or `kdb get`
+the same validation is also done by `kdb validate`
 Only string keys are validated! Binary keys are skipped!
 
-Use -f to do a write test even if the previous read
+Use `-f` to do a write-test even if the previous read
 from the key database has issued warnings.
 
 ## OPTIONS
 
 - `-d`,`--debug`:
-  Give debug information or ask debug questions (in interactive mode).
+  Give debug information.
 - `-f`, `--force`:
-  Force the action to be done.
+Force writing the configuration even on warnings.
 - `-H`, `--help`:
   Show the man page.
 - `-p <name>`, `--profile <name>`:
diff --git a/doc/man/man1/kdb-validate.1 b/doc/man/man1/kdb-validate.1
index 288bfbf5f43..f129462a002 100644
--- a/doc/man/man1/kdb-validate.1
+++ b/doc/man/man1/kdb-validate.1
@@ -1,37 +1,52 @@
-.\" generated with Ronn-NG/v0.10.1
-.\" http://github.com/apjanke/ronn-ng/tree/0.10.1.pre1
-.TH "KDB\-VALIDATE" "1" "January 2022" ""
+.\" generated with Ronn/v0.7.3
+.\" http://github.com/rtomayko/ronn/tree/0.7.3
+.
+.TH "KDB\-VALIDATE" "1" "January 2022" "" ""
+.
 .SH "NAME"
 \fBkdb\-validate\fR \- Validate key values
+.
 .SH "SYNOPSIS"
 \fBkdb validate\fR
+.
 .SH "DESCRIPTION"
 Validate the values of string keys below a given name using the loaded validation plugins (eg\. range or validation) by reading all values, making them dirty by changing to another value, changing back to original and then writing that back to the key database\.
+.
 .P
 This command is useful for validating configuration files against their specifications\.
+.
 .P
-For keys to be validated, they must contain the 'check'\-metakeys and the respective plugins for validation must be loaded for the backend that was used while mounting\. If a validation is done while using 'kdb set' the same validation is also done by 'kdb validate' Only string keys are validated! Binary keys are skipped!
+For keys to be validated, they must contain the \'check\'\-metakeys and the respective plugins for validation must be loaded for the backend that was used while mounting\. If a validation is done while using \fBkdb set\fR or \fBkdb get\fR the same validation is also done by \fBkdb validate\fR Only string keys are validated! Binary keys are skipped!
+.
 .P
-Use \-f to do a write test even if the previous read from the key database has issued warnings\.
+Use \fB\-f\fR to do a write\-test even if the previous read from the key database has issued warnings\.
+.
 .SH "OPTIONS"
+.
 .TP
 \fB\-d\fR,\fB\-\-debug\fR
-Give debug information or ask debug questions (in interactive mode)\.
+Give debug information\.
+.
 .TP
 \fB\-f\fR, \fB\-\-force\fR
-Force the action to be done\.
+Force writing the configuration even on warnings\.
+.
 .TP
 \fB\-H\fR, \fB\-\-help\fR
 Show the man page\.
+.
 .TP
 \fB\-p <name>\fR, \fB\-\-profile <name>\fR
 Use a different profile for kdb configuration\.
+.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 Explain what is happening\.
+.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
 Print version info\.
+.
 .TP
 \fB\-C <when>\fR, \fB\-\-color <when>\fR
 Print \fBnever/auto(default)/always\fR colored output\.
diff --git a/src/libs/tools/include/errors/baseNotification.hpp b/src/libs/tools/include/errors/baseNotification.hpp
index b819542d6a1..af2908d5682 100644
--- a/src/libs/tools/include/errors/baseNotification.hpp
+++ b/src/libs/tools/include/errors/baseNotification.hpp
@@ -12,9 +12,11 @@ namespace tools
 {
 namespace errors
 {
-/* common abstract class for warnings and errors */
-/* Because warning and errors share the same data members, a method can accept a ErrBase argument and the caller
- * can create an Error or a Warning based on the provided object. */
+/* Common abstract class for warnings and errors.
+ * Because warning and errors share the same data members,
+ * a method can accept a BaseNotification argument and
+ * the caller can create an Error or a Warning
+ * based on the provided object. */
 class BaseNotification
 {
 public:
@@ -46,7 +48,6 @@ class BaseNotification
 
 	/* string representation */
 	friend std::ostream& operator<< (std::ostream& outputStream, const BaseNotification& eb);
-	/* compare */
 
 	/**
 	 * @brief Compare fields of notification objects
diff --git a/src/libs/tools/include/errors/error.hpp b/src/libs/tools/include/errors/error.hpp
index 5ed171b9cd0..649dd11dc55 100644
--- a/src/libs/tools/include/errors/error.hpp
+++ b/src/libs/tools/include/errors/error.hpp
@@ -23,10 +23,13 @@ class Error : public BaseNotification
 	/**
 	 * @brief Add a warning to an error
 	 *
-	 * The warning is copied to make it independent from the source object. This way the same warning added to two different errors can be
+	 * The warning is copied to make it independent from the source object.
+	 * This way the same warning added to two different errors can be
 	 * changed independently.
 	 *
-	 * An Error can contain 0 to n warnings.
+	 * An object of type `Error` can contain 0 to n warnings,
+	 * like Keys in the C-API can contain one error,
+	 * but multiple warnings.
 	 *
 	 * @param warning the warning to add
 	 */
diff --git a/src/libs/tools/include/errors/errorTypes.hpp b/src/libs/tools/include/errors/errorTypes.hpp
index 2c1484892c6..d66f46a4a7b 100644
--- a/src/libs/tools/include/errors/errorTypes.hpp
+++ b/src/libs/tools/include/errors/errorTypes.hpp
@@ -11,7 +11,10 @@ namespace tools
 namespace errors
 {
 
-/* Not an error by itself, but a container for multiple warnings */
+/* Not an Error by itself, but a container for multiple Warnings,
+ * like keys in the C-API have at most one error, but 0 to n warnings.
+ * This way the content of such a key can be stored in a single Error object,
+ * even if the key doesn't contain an actual error. */
 class PureWarningError : public Error
 {
 public:
diff --git a/src/tools/kdb/validate.cpp b/src/tools/kdb/validate.cpp
index 962d8fd0245..e971c6863b5 100644
--- a/src/tools/kdb/validate.cpp
+++ b/src/tools/kdb/validate.cpp
@@ -100,9 +100,10 @@ int ValidateCommand::execute (Cmdline const & cl)
 		/* do lookup (needed for resolving cascading keys) */
 		Key lookupKey = ksPart.lookup (curKey);
 
-		if (lookupKey.isBinary ()) continue; // only validate string keys
+		/* only validate string keys */
+		if (lookupKey.isBinary ()) continue;
 
-		/* change value (to enable sync flag */
+		/* change value to enable sync flag */
 		lookupKey.setString (lookupKey.getString () + "^");
 
 		/* change value back to original */