docs

Author: lia-viam

src/viam/sdk/log/logger.cpp

@@ -90,6 +90,10 @@ Logger& Logger::get() {
     return result;
 }
 
+LogSource& Logger::logger() {
+    return sdk_logger_;
+}
+
 void Logger::set_global_log_level(log_level lvl) {
     global_level_ = lvl;
 }

src/viam/sdk/log/logger.hpp

@@ -1,3 +1,6 @@
+/// @file log/logger.hpp
+///
+/// @brief Defines logging infrastructure
 #pragma once
 
 #include <cstdint>
@@ -16,6 +19,10 @@
 namespace viam {
 namespace sdk {
 
+/// @defgroup Log Classes related to logging.
+
+/// @brief Severity levels for the logger.
+/// @ingroup Log
 enum class log_level : std::int8_t {
     trace = -2,
     debug = -1,
@@ -31,10 +38,23 @@ log_level level_from_string(std::string level);
 
 std::ostream& operator<<(std::ostream&, log_level);
 
+/// @brief Type alias for the log source in the C++ SDK.
+/// @ingroup Log
+///
+/// In the paradigm of Boost.Log the C++ SDK has precisely one logging source, namely the source of
+/// messages generated by the user invoking one of the logging macros.
 using LogSource = boost::log::sources::severity_channel_logger_mt<log_level>;
 
+/// @brief Returns the "channel name" of general log messages not originating from resources.
+/// @ingroup Log
 std::string global_resource_name();
 
+/// @class Logger logger.hpp "log/logger.hpp"
+/// @brief Manages the logging infrastructure in the SDDK.
+/// @ingroup Log
+///
+/// Handles initialization and bookkeeping for logging infrastructure in the C++ SDK. This includes
+/// console logging, if active, and both global and resource-level log filtering.
 class Logger {
    public:
     struct Filter {
@@ -43,29 +63,47 @@ class Logger {
         bool operator()(const boost::log::attribute_value_set&);
     };
 
+    /// @brief Returns the unique logger instance.
+    ///
+    /// This is the only way to access the logger.
     static Logger& get();
 
+    /// @brief Set the global logger severity.
     void set_global_log_level(log_level);
 
-    /// @brief Set the SDK logger severity from a command line argument vector.
+    /// @brief Set the global logger severity from a command line argument vector.
     ///
-    /// Sets the boost trivial logger's severity to debug if "--log-level=debug" is the
+    /// Sets severity to debug if "--log-level=debug" is
     /// the third argument. Sets severity to info otherwise. Useful for module
     /// implementations. See LogLevel documentation in the RDK for more information on
     /// how to start modules with a "log-level" commandline argument.
     void set_global_log_level(int argc, char** argv);
 
+    /// @brief Set the logger severity for a resource.
+    ///
+    /// Logger can maintain separate severity levels for individual resources. For example, you may
+    /// want to only report "error" messages for global logs and logs for one component of a modular
+    /// resource, but enable verbose logging for a new component that is still being debugged.
+    /// @see @ref Resource, which has a set_log_level method which automatically provides its own
+    /// resource name.
     void set_resource_log_level(const std::string& resource, log_level);
 
-    LogSource& logger() {
-        return sdk_logger_;
-    }
+    /// @brief Return the SDK global log source.
+    ///
+    /// Users should prefer to log messages using the logging macros below.
+    LogSource& logger();
 
    private:
     friend class RobotClient;
     friend class Instance;
     Logger() = default;
 
+    Logger(const Logger&) = delete;
+    Logger(Logger&&) = delete;
+
+    Logger& operator=(const Logger&) = delete;
+    Logger& operator=(Logger&&) = delete;
+
     void init_logging();
     void disable_console_logging();
 
@@ -86,14 +124,23 @@ BOOST_LOG_ATTRIBUTE_KEYWORD_TYPE(attr_time,
                                  "TimeStamp",
                                  boost::log::attributes::local_clock::value_type);
 
-// Logging macro for general SDK logs
 #define VIAM_LOG_IMPL(lg, level)                                            \
     BOOST_LOG_SEV((lg), ::viam::sdk::log_level::level)                      \
         << ::boost::log::add_value(::viam::sdk::attr_file_type{}, __FILE__) \
         << ::boost::log::add_value(::viam::sdk::attr_line_type{}, __LINE__)
 
+/// @brief Log macro for general SDK logs.
+/// @ingroup Log
+///
+/// Use this macro to generate log messages pertaining to the SDK at large.
 #define VIAM_LOG(level) VIAM_LOG_IMPL(::viam::sdk::Logger::get().logger(), level)
 
+/// @brief Log macro for resource-level logs.
+/// @ingroup Log
+///
+/// This macro can only be called from the definition of a member function of a class inheriting
+/// @ref Resource. It will log messages to the log source of that specific resource, allowing
+/// resource-level log filtering.
 #define VIAM_RESOURCE_LOG(level) VIAM_LOG_IMPL(this->logger_, level)
 
 }  // namespace sdk

src/viam/sdk/log/private/log_backend.hpp

@@ -14,6 +14,7 @@ struct LogBackend;
 
 using SinkType = boost::log::sinks::synchronous_sink<LogBackend>;
 
+// Log backend which implements sending messages to RDK.
 struct LogBackend : boost::log::sinks::basic_sink_backend<boost::log::sinks::synchronized_feeding> {
     LogBackend(RobotClient* p) : parent(p) {}