libtools: fix or clarify most aspects that were reviewd in the PR #4224…

… by @markus2330

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>`:

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\.

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

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
 	 */

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:

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 */