Revision by Hannah + ready to merge after this

src/util/Log.h

@@ -1,6 +1,8 @@
-// Copyright 2011, University of Freiburg,
-// Chair of Algorithms and Data Structures.
-// Author: Björn Buchhold ([email protected])
+// Copyright 2011 - 2024, University of Freiburg
+// Chair of Algorithms and Data Structures
+// Authors: Björn Buchhold <[email protected]> [2011 - 2014]
+//          Johannes Kalmbach <[email protected]>
+//          Hannah Bast <[email protected]>
 
 #pragma once
 
@@ -20,12 +22,14 @@
 #define LOGLEVEL INFO
 #endif
 
-// Abseil does also define its own LOG macro, so we need to undefine it here.
-// NOTE: In case you run into trouble with this conflict, in particular if you
-// use the `LOG()` macro and you get compilation errors that mention `abseil`,
-// use the (otherwise identical) `AD_LOG` macro below. Same goes for the
-// loglevels, use for example `AD_DEBUG` instead of `DEBUG`.
-// TODO<joka921> Consistently replace the `LOG` macro by `AD_LOG`.
+// Abseil also defines its own LOG macro, so we need to undefine it here.
+//
+// NOTE: In case you run into trouble with this conflict, in particular, if you
+// use the `LOG(INFO)` macro and you get compilation errors that mention
+// `abseil`, use the (otherwise identical) `AD_LOG_INFO` macro below.
+//
+// TODO<joka921>: Eventually replace the `LOG` macro by `AD_LOG` everywhere.
+
 #ifdef LOG
 #undef LOG
 #endif
@@ -52,8 +56,8 @@ enum class LogLevel {
   TRACE = 6
 };
 
-// These should be used in new code to avoid clashes with `abseil` (similar to
-// `AD_LOG` vs `LOG`), see above for details.
+// Macros for the different log levels. Always use these instead of the old
+// `LOG(...)` macro to avoid conflicts with `abseil`.
 #define AD_LOG_FATAL AD_LOG(LogLevel::FATAL)
 #define AD_LOG_ERROR AD_LOG(LogLevel::ERROR)
 #define AD_LOG_WARN AD_LOG(LogLevel::WARN)
@@ -65,10 +69,8 @@ enum class LogLevel {
 using enum LogLevel;
 
 namespace ad_utility {
-/* A singleton (According to Scott Meyer's pattern) that holds
- * a pointer to a single std::ostream. This enables us to globally
- * redirect the LOG(LEVEL) macros to another location.
- */
+// A singleton that holds a pointer to a single `std::ostream`. This enables us
+// to globally redirect the `AD_LOG_...` macros to another output stream.
 struct LogstreamChoice {
   std::ostream& getStream() { return *_stream; }
   void setStream(std::ostream* stream) { _stream = stream; }
@@ -86,19 +88,15 @@ struct LogstreamChoice {
 
   // default to cout since it was the default before
   std::ostream* _stream = &std::cout;
+};
 
-};  // struct LogstreamChoice
-
-/** @brief Redirect every LOG(LEVEL) macro that is called afterwards
- *         to the stream that the argument points to.
- *         Typically called in the main function of an executable.
- */
-inline void setGlobalLoggingStream(std::ostream* streamPtr) {
-  LogstreamChoice::get().setStream(streamPtr);
+// After this call, every use of `AD_LOG_...` will use the specified stream.
+// Used in various tests to redirect or suppress logging output.
+inline void setGlobalLoggingStream(std::ostream* stream) {
+  LogstreamChoice::get().setStream(stream);
 }
 
-using std::string;
-//! Helper class to get thousandth separators in a locale
+// Helper class to get thousandth separators in a locale
 class CommaNumPunct : public std::numpunct<char> {
  protected:
   virtual char do_thousands_sep() const { return ','; }
@@ -108,7 +106,7 @@ class CommaNumPunct : public std::numpunct<char> {
 
 const static std::locale commaLocale(std::locale(), new CommaNumPunct());
 
-//! Log
+// The class that actually does the logging.
 class Log {
  public:
   template <LogLevel LEVEL>
@@ -120,7 +118,7 @@ class Log {
 
   static void imbue(const std::locale& locale) { std::cout.imbue(locale); }
 
-  static string getTimeStamp() {
+  static std::string getTimeStamp() {
     return absl::FormatTime("%Y-%m-%d %H:%M:%E3S", absl::Now(),
                             absl::LocalTimeZone());
   }