Merge branch 'clarify_msgstream' into 'master'

Clarify use of MsgStream macros

See merge request !1

rules.org

@@ -1988,6 +1988,11 @@ private:
    Athena-aware could use =cerr= before throwing an exception, but all
    Athena-aware classes should use =MSG::FATAL= and/or throw an exception.
 
+   When using =MsgStream=, note that a call to e.g. =msg() << MSG::VERBOSE= that is suppressed by the output level has a higher runtime cost than
+   a call suppressed by =if (msgLvl <= MSG::VERBOSE)=. The =ATH_MSG= macros (=ATH_MSG_INFO= and =ATH_MSG_DEBUG= etc) wrap =msg()= calls in appropriate if statements and
+   are preferred in general for two reasons: they take up less space in the source code and indicate immediately that the message is correctly handled.
+   
+
 
  - *Check for all errors reported from functions.* [<<check-return-status>>]