Add description for test hints

programs/client/TestHint.h

@@ -11,9 +11,35 @@
 namespace DB
 {
 
-/// Checks expected server and client error codes in testmode.
+/// Checks expected server and client error codes in --testmode.
-/// To enable it add special comment after the query: "-- { serverError 60 }" or "-- { clientError 20 }".
+///
-/// Also you can enable echoing all queries by writing "-- { echo }".
+/// The following comment hints are supported:
+///
+/// - "-- { serverError 60 }" -- in case of you are expecting server error.
+///
+/// - "-- { clientError 20 }" -- in case of you are expecting client error.
+///
+///   Remember that the client parse the query first (not the server), so for
+///   example if you are expecting syntax error, then you should use
+///   clientError not serverError.
+///
+/// Examples:
+///
+/// - echo 'select / -- { clientError 62 }' | clickhouse-client --testmode -nm
+///
+//    Here the client parses the query but it is incorrect, so it expects
+///   SYNTAX_ERROR (62).
+///
+/// - echo 'select foo -- { serverError 47 }' | clickhouse-client --testmode -nm
+///
+///   But here the query is correct, but there is no such column "foo", so it
+///   is UNKNOWN_IDENTIFIER server error.
+///
+/// The following hints will control the query echo mode (i.e print each query):
+///
+/// - "-- { echo }"
+/// - "-- { echoOn }"
+/// - "-- { echoOff }"
 class TestHint
 {
 public: