Review/add the API doc (logging) (#1201)

In olp-cpp-sdk-core/include/olp/core/logging,
review and modify the existing documentation and add missing
descriptions so that we have fewer errors when building the API ref.

Relates-To: OLPEDGE-1446
Signed-off-by: Halyna Dumych <[email protected]>

Author: HalynaDumych

olp-cpp-sdk-core/include/olp/core/logging/Appender.h

@@ -24,18 +24,18 @@
 namespace olp {
 namespace logging {
 /**
- * @brief Abstract base class for an appender, which appends a message to the
- * log.
+ * @brief Appends a message to the log.
  *
- * Subclasses should derive from Appender instead of IAppender in order for the
- * type to be automatically registered.
+ * To automatically register the type, base subclasses on
+ * `Appender` instead of `IAppender`.
  */
 class CORE_API IAppender {
  public:
   virtual ~IAppender() = default;
 
   /**
-   * @brief Appends a message using char strings.
+   * @brief Appends the message using char strings.
+   *
    * @param message The message to append.
    */
   virtual IAppender& append(const LogMessage& message) = 0;

olp-cpp-sdk-core/include/olp/core/logging/Configuration.h

@@ -30,20 +30,19 @@
 namespace olp {
 namespace logging {
 /**
- * @brief Class for configuring the appenders and loggers available by the
- * logging system.
+ * @brief Configures appenders and loggers available in
+ * the logging system.
  */
 class CORE_API Configuration {
  public:
   /**
-   * @brief Struct containing an appender and a log level that the appender is
-   * enabled with.
+   * @brief Contains an appender and its log level.
    */
   struct AppenderWithLogLevel {
     /**
-     * @brief The log level the appender is enabled with.
+     * @brief The log level of the appender.
      *
-     * Any log levels less than this level will be ignored.
+     * Any log level that is less than this level is ignored.
      */
     logging::Level logLevel;
 
@@ -53,7 +52,8 @@ class CORE_API Configuration {
     std::shared_ptr<IAppender> appender;
 
     /**
-     * @brief Checks to see if the appender is enabled for a log level.
+     * @brief Checks whether the appender is enabled for the log level.
+     *
      * @param level The log level.
      */
     bool isEnabled(logging::Level level) const {
@@ -62,27 +62,30 @@ class CORE_API Configuration {
   };
 
   /**
-   * @brief Typedef for a list of appenders
+   * @brief A typedef for a list of appenders.
    */
   using AppenderList = std::vector<AppenderWithLogLevel>;
 
   /**
-   * @brief Creates a default configuration by adding the DebugAppender and the
-   * ConsoleAppender as appenders.
+   * @brief Creates a default configuration by adding
+   * an instance of `DebugAppender` and `ConsoleAppender` as appenders.
+   *
    * @return The default configuration.
    */
   static Configuration createDefault();
 
   /**
-   * @brief Returns whether or not the configuration is valid.
-   * @return Whether or not the configuration is valid.
+   * @brief Checks whether the configuration is valid.
+   *
+   * @return True if the configuration is valid; false otherwise.
    */
   inline bool isValid() const;
 
   /**
-   * @brief Adds an appender along with its logging level to the configuration.
+   * @brief Adds the appender along with its log level to the configuration.
+   *
    * @param appender The appender to add.
-   * @param level The log level belonging to appender.
+   * @param level The log level of the appender.
    */
   inline Configuration& addAppender(
       std::shared_ptr<IAppender> appender,
@@ -95,7 +98,8 @@ class CORE_API Configuration {
 
   /**
    * @brief Gets the appenders from the configuration.
-   * @return The appenders and belonging log levels.
+   *
+   * @return The appenders and their log levels.
    */
   inline const AppenderList& getAppenders() const;
 

olp-cpp-sdk-core/include/olp/core/logging/ConsoleAppender.h

@@ -28,25 +28,28 @@
 namespace olp {
 namespace logging {
 /**
- * @brief Appender for printing to the console.
+ * @brief An appender that prints messages to the console.
  */
 class CORE_API ConsoleAppender : public IAppender {
  public:
   /**
-   * @brief Constructs this with the message formatter.
+   * @brief Creates a `ConsoleAppender` instance with a message formatter.
+   *
    * @param formatter The message formatter.
    */
   inline explicit ConsoleAppender(
       MessageFormatter formatter = MessageFormatter::createDefault());
 
   /**
    * @brief Gets the message formatter.
+   *
    * @return The message formatter.
    */
   inline const MessageFormatter& getMessageFormatter() const;
 
   /**
    * @brief Sets the message formatter.
+   *
    * @param formatter The message formatter.
    */
   inline ConsoleAppender& setMessageFormatter(MessageFormatter formatter);

olp-cpp-sdk-core/include/olp/core/logging/DebugAppender.h

@@ -25,14 +25,14 @@
 namespace olp {
 namespace logging {
 /**
- * @brief Appender for printing to the debug output.
+ * @brief An appender that prints messages to the debug output.
  */
 class CORE_API DebugAppender : public IAppender {
  public:
   /**
-   * @brief Returns whether or not the debug appender is implemented for this
-   * platform.
-   * @return Whether or not this is implemented.
+   * @brief Checks whether this platform has the debug appender implemented.
+   *
+   * @return True if this platform has the debug appender; false otherwise.
    */
   static bool isImplemented();
 

olp-cpp-sdk-core/include/olp/core/logging/FileAppender.h

@@ -30,14 +30,15 @@
 namespace olp {
 namespace logging {
 /**
- * @brief Appender for printing to a file.
+ * @brief An appender that prints messages to a file.
  */
 class CORE_API FileAppender : public IAppender {
  public:
   /**
-   * @brief Constructs a file appender.
+   * @brief Creates a `FileAppender` instance.
+   *
    * @param fileName The name of the file to write to.
-   * @param append True to append to an existing file if it exists.
+   * @param append True to append to an existing file; false otherwise.
    * @param formatter The message formatter.
    */
   explicit FileAppender(
@@ -46,31 +47,36 @@ class CORE_API FileAppender : public IAppender {
   ~FileAppender() override;
 
   /**
-   * @brief Returns whether or not the stream is opened and can be written to.
-   * @return True if this is valid.
+   * @brief Checks whether the stream is open and can be written to.
+   *
+   * @return True if the stream is open and can be written to; false otherwise.
    */
   bool isValid() const;
 
   /**
-   * @brief Gets the name of the file this was created with.
+   * @brief Gets the name of the file.
+   *
    * @return The file name.
    */
   inline const std::string& getFileName() const;
 
   /**
-   * @brief Returns whether or not the file is being appended to.
-   * @return True if appending to the file.
+   * @brief Checks whether the file has the appender.
+   *
+   * @return True if the file has the appender; false otherwise.
    */
   inline bool getAppendFile() const;
 
   /**
    * @brief Gets the message formatter.
+   *
    * @return The message formatter.
    */
   inline const MessageFormatter& getMessageFormatter() const;
 
   /**
    * @brief Sets the message formatter.
+   *
    * @param formatter The message formatter.
    */
   inline FileAppender& setMessageFormatter(MessageFormatter formatter);

olp-cpp-sdk-core/include/olp/core/logging/FilterGroup.h

@@ -33,98 +33,120 @@
 namespace olp {
 namespace logging {
 /**
- * @brief Class that groups together log levels for different tags. This makes
- * it easier to apply groups of level filters together.
+ * @brief Groups together log levels for different tags.
+ *
+ * It helps to apply groups of level filters together.
  */
 class CORE_API FilterGroup {
  public:
   inline FilterGroup();
+
+  /// The default copy constructor.
   FilterGroup(const FilterGroup&) = default;
+
+  /// The default copy assignment operator.
   FilterGroup& operator=(const FilterGroup&) = default;
+
+  /// The default move constructor.
   inline FilterGroup(FilterGroup&& other) noexcept;
+
+  /// The default move assignment operator.
   inline FilterGroup& operator=(FilterGroup&& other) noexcept;
 
   /**
    * @brief Gets the default log level.
-   * @return The default log level, or boost::none if not set.
+   *
+   * @return The default log level or `boost::none` if the level is not set.
    */
   inline boost::optional<Level> getLevel() const;
 
   /**
    * @brief Sets the default log level.
+   *
    * @param level The default log level.
    */
   inline FilterGroup& setLevel(Level level);
 
   /**
-   * @brief Clears the default log level to be unset.
+   * @brief Clears the default log level.
    *
-   * Leaving the default log level unset prevents the default level in Log from
-   * changing when the filter group is applied.
+   * If the default log level is unset, it does not change
+   * when the filter group is applied.
    */
   inline FilterGroup& clearLevel();
 
   /**
-   * @brief Gets the log level for a tag
-   * @param tag The tag to get the log level for.
-   * @return The log level for the tag, or boost::none if not set.
+   * @brief Gets the log level for a tag.
+   *
+   * @param tag The tag for which to get the log level.
+   *
+   * @return The log level for the tag, or `boost::none` if the level is not set.
    */
   inline boost::optional<Level> getLevel(const std::string& tag) const;
 
   /**
    * @brief Sets the log level for a tag.
+   *
    * @param level The log level for a tag.
-   * @param tag The tag to set the level for.
+   * @param tag The tag for which to set the level.
    */
   inline FilterGroup& setLevel(Level level, const std::string& tag);
 
   /**
-   * @brief Clears the log level to be unset for a tag.
+   * @brief Clears the log level for a tag.
    *
-   * Leaving the log level for a tag unset causes it to use the default log
-   * level instead.
+   * If the log level for a tag is unset, the default log
+   * level is used instead.
    */
   inline FilterGroup& clearLevel(const std::string& tag);
 
   /**
-   * @brief Clears the filter group to be unset.
+   * @brief Clears the filter group.
    */
   inline FilterGroup& clear();
 
   /**
    * @brief Loads the filter group from a file.
-   * @param fileName The file to load the configuration from.
-   * @return Whether or not the load was successful. If unsuccessful, this will
-   * be cleared.
+   *
+   * @param fileName The file from which to load the configuration.
+   *
+   * @return True if the load was successful; false otherwise. If unsuccessful,
+   * this is cleared.
    */
   bool load(const std::string& fileName);
 
   /**
    * @brief Loads the filter group from a stream.
    *
-   * The stream is expected contain text data. The format is as follows:
-   *     - Blank lines, or lines that start with # are ignored.
-   *     - Setting the log level for the tag is of the format "tag: level". For
-   * example:
-   *         - mylib: warning
-   *         - theirlib: info
-   *         - otherlib: off
-   *     - Setting the default log level is of the format ": level". For
-   * example: ": error"
-   *     - Whitespace is trimmed and case is ignored for the levels.
+   * The stream should contain text data.
+   * The format of the stream:
+   * - Blank lines or lines that start with "#" are ignored.
+   * - Use the following format for tag log levels: `tag: level`.
+   * For example:
+   *    - `mylib: warning`
+   *    - `theirlib: info`
+   *    - `otherlib: off`
+   * - Use the following format for the default log level: `: level`.
+   * For example: `: error`
+   * - Whitespaces are trimmed.
+   * - The case is ignored for levels.
    *
-   * The filter group will be cleared before the contents of the stream are
+   * The filter groups are cleared before the content of the stream is
    * applied.
-   * @param stream The stream to load the configuration from.
-   * @return Whether or not the load was successful. If unsuccessful, this will
-   * be cleared.
+   *
+   * @param stream The stream from which to load the configuration.
+   *
+   * @return True if the load was successful; false otherwise. If unsuccessful,
+   * this is cleared.
    */
   bool load(std::istream& stream);
 
   /**
-   * @brief Converts string logging level to enum Level format.
-   * @param levelStr string level to convert.
-   * @return Converted level
+   * @brief Converts the string log level to the enum level format.
+   *
+   * @param levelStr The string level to convert.
+   *
+   * @return The converted level.
    */
   static boost::optional<Level> stringToLevel(const std::string& levelStr);