Updated doc comments

logdoctor/modules/blacklists/blacklists.h

@@ -17,53 +17,92 @@ struct Blacklists final
 
     explicit Blacklists() noexcept = default;
 
-    //! \throw DoNotCatchException
+    //! Returns whether the requested blacklist is in use
+    /*!
+        \throw DoNotCatchException
+    */
     inline bool isUsed( const WebServer ws, const BlacklistField fld )
     { return get( ws ).isUsed( fld ); }
 
-    //! \throw DoNotCatchException
+    //! Sets the requested blacklist in the given in-use condition
+    /*!
+        \throw DoNotCatchException
+    */
     inline void setUsed( const WebServer ws, const BlacklistField fld, const bool used )
     { get( ws ).setUsed( fld, used ); }
 
-    //! \throw DoNotCatchException
+    //! Returns a const reference to the requested blacklist
+    /*!
+        \throw DoNotCatchException
+    */
     const Blacklist& getConst( const WebServer ws ) const;
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested blacklist
+    /*!
+        \throw DoNotCatchException
+    */
     Blacklist& get( const WebServer ws );
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested blacklist
+    /*!
+        \throw DoNotCatchException
+    */
     inline BlacklistItem& get( const WebServer ws, const BlacklistField fld )
     { return get( ws ).get( fld ); }
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested blacklist
+    /*!
+        \throw DoNotCatchException
+    */
     inline std::vector<std::string>& getList( const WebServer ws, const BlacklistField fld )
     { return get( ws, fld ).list; }
 
-    //! \throw DoNotCatchException
+    //! Returns a const reference to the requested blacklist
+    /*!
+        \throw DoNotCatchException
+    */
     inline const std::vector<std::string>& getListConst( const WebServer ws, const BlacklistField fld )
     { return get( ws, fld ).list; }
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Replaces the requested blacklist with the one provided
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     inline void setList( const WebServer ws, const BlacklistField fld, const std::vector<std::string>& list )
     { get( ws, fld ).set( list ); }
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Clears the requested blacklist
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     inline void clearList( const WebServer ws, const BlacklistField fld )
     { getList( ws, fld ).clear(); }
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Adds the provided item to the requested blacklist
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     inline void addItem( const WebServer ws, const BlacklistField fld, const std::string& item )
     { get( ws, fld ).add( item ); }
 
-    //! \throw BWlistException
+    //! Remove the requested item from the requested blacklist
+    /*!
+        \throw BWlistException
+    */
     inline void removeItem( const WebServer ws, const BlacklistField fld, const std::string& item )
     { get( ws, fld ).remove( item ); }
 
-    //! \throw BWlistException
+    //! Moves the requested item one position up in the requested blacklist
+    /*!
+        \throw BWlistException
+    */
     inline int moveUpItem( const WebServer ws, const BlacklistField fld, const std::string& item )
     { return get( ws, fld ).moveUp( item ); }
 
-    //! \throw BWlistException
+    //! Moves the requested item one position down in the requested blacklist
+    /*!
+        \throw BWlistException
+    */
     inline int moveDownItem( const WebServer ws, const BlacklistField fld, const std::string& item )
     { return get( ws, fld ).moveDown( item ); }
 };

logdoctor/modules/blacklists/modules/blacklist.h

@@ -11,14 +11,23 @@ struct Blacklist final
 
     explicit Blacklist() noexcept;
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested blacklist item
+    /*!
+        \throw DoNotCatchException
+    */
     BlacklistItem& get( const BlacklistField field );
 
-    //! \throw DoNotCatchException
+    //! Returns whether the requested blacklist is in use
+    /*!
+        \throw DoNotCatchException
+    */
     inline bool isUsed( const BlacklistField field )
     { return get( field ).used; }
 
-    //! \throw DoNotCatchException
+    //! Sets the requested blacklist in the given in-use condition
+    /*!
+        \throw DoNotCatchException
+    */
     inline void setUsed( const BlacklistField field, const bool used )
     { get( field ).used = used; }
 };

logdoctor/modules/blacklists/modules/blacklist_item.h

@@ -19,26 +19,52 @@ struct BlacklistItem final
     BlacklistItem( const bool use, const BlacklistField fld ) noexcept
         : used{use}, field{fld} {}
 
-    //! \throw DoNotCatchException
+    //! Returns the name of the field to which the list is associated
+    /*!
+        The name is translatable
+        \throw DoNotCatchException
+    */
     const char* fieldName() const;
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Replaces the current list with the one provided
+    /*!
+        All the items will be sanitized before actually
+        becoming part of the list
+        \throw BWlistException, DoNotCatchException
+    */
     void set( const std::vector<std::string>& new_list );
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Adds the provided item to the list
+    /*!
+        The item will be sanitized before actually
+        being added to the list
+        \throw BWlistException, DoNotCatchException
+    */
     void add( const std::string& item );
 
-    //! \throw BWlistException
+    //! Remove the requested item from the list
+    /*!
+        \throw BWlistException
+    */
     void remove( const std::string& item );
 
-    //! \throw BWlistException
+    //! Moves the requested item one position up in the list
+    /*!
+        \throw BWlistException
+    */
     int moveUp( const std::string& item );
 
-    //! \throw BWlistException
+    //! Moves the requested item one position down in the list
+    /*!
+        \throw BWlistException
+    */
     int moveDown( const std::string& item );
 
 private:
-    //! \throw BWlistException, DoNotCatchException
+    //! Returns a sanitized item
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     std::string sanitized( const std::string& item ) const;
 };
 

logdoctor/modules/warnlists/modules/warnlist.h

@@ -14,14 +14,23 @@ struct Warnlist final
 
     explicit Warnlist() noexcept;
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested warnlist item
+    /*!
+        \throw DoNotCatchException
+    */
     WarnlistItem& get( const WarnlistField field );
 
-    //! \throw DoNotCatchException
+    //! Returns whether the requested warnlist is in use
+    /*!
+        \throw DoNotCatchException
+    */
     inline bool isUsed( const WarnlistField field )
     { return get( field ).used; }
 
-    //! \throw DoNotCatchException
+    //! Sets the requested warnlist in the given in-use condition
+    /*!
+        \throw DoNotCatchException
+    */
     inline void setUsed( const WarnlistField field, const bool used )
     { get( field ).used = used; }
 };

logdoctor/modules/warnlists/modules/warnlist_item.h

@@ -19,26 +19,52 @@ struct WarnlistItem final
     WarnlistItem( const bool use, const WarnlistField fld ) noexcept
         : used{use}, field{fld} {}
 
-    //! \throw DoNotCatchException
+    //! Returns the name of the field to which the list is associated
+    /*!
+        The name is translatable
+        \throw DoNotCatchException
+    */
     const char* fieldName() const;
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Replaces the current list with the one provided
+    /*!
+        All the items will be sanitized before actually
+        becoming part of the list
+        \throw BWlistException, DoNotCatchException
+    */
     void set( const std::vector<std::string>& new_list );
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Adds the provided item to the list
+    /*!
+        The item will be sanitized before actually
+        being added to the list
+        \throw BWlistException, DoNotCatchException
+    */
     void add( const std::string& item );
 
-    //! \throw BWlistException
+    //! Remove the requested item from the list
+    /*!
+        \throw BWlistException
+    */
     void remove( const std::string& item );
 
-    //! \throw BWlistException
+    //! Moves the requested item one position up in the list
+    /*!
+        \throw BWlistException
+    */
     int moveUp( const std::string& item );
 
-    //! \throw BWlistException
+    //! Moves the requested item one position down in the list
+    /*!
+        \throw BWlistException
+    */
     int moveDown( const std::string& item );
 
 private:
-    //! \throw BWlistException, DoNotCatchException
+    //! Returns a sanitized item
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     std::string sanitized( const std::string& item ) const;
 };
 

logdoctor/modules/warnlists/warnlists.h

@@ -15,50 +15,86 @@ struct Warnlists final
 
     explicit Warnlists() noexcept = default;
 
-    //! \throw DoNotCatchException
+    //! Returns whether the requested warnlist is in use
+    /*!
+        \throw DoNotCatchException
+    */
     inline bool isUsed( const WebServer ws, const WarnlistField fld )
     { return get( ws ).isUsed( fld ); }
 
-    //! \throw DoNotCatchException
+    //! Sets the requested warnlist in the given in-use condition
+    /*!
+        \throw DoNotCatchException
+    */
     inline void setUsed( const WebServer ws, const WarnlistField fld, const bool used )
     { get( ws ).setUsed( fld, used ); }
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested warnlist
+    /*!
+        \throw DoNotCatchException
+    */
     Warnlist& get( const WebServer ws );
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested warnlist
+    /*!
+        \throw DoNotCatchException
+    */
     inline WarnlistItem& get( const WebServer ws, const WarnlistField fld )
     { return get( ws ).get( fld ); }
 
-    //! \throw DoNotCatchException
+    //! Returns a reference to the requested warnlist
+    /*!
+        \throw DoNotCatchException
+    */
     inline std::vector<std::string>& getList( const WebServer ws, const WarnlistField fld )
     { return get( ws, fld ).list; }
 
-    //! \throw DoNotCatchException
+    //! Returns a const reference to the requested warnlist
+    /*!
+        \throw DoNotCatchException
+    */
     inline const std::vector<std::string>& getListConst( const WebServer ws, const WarnlistField fld )
     { return get( ws, fld ).list; }
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Replaces the requested warnlist with the one provided
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     inline void setList( const WebServer ws, const WarnlistField fld, const std::vector<std::string>& list )
     { get( ws, fld ).set( list ); }
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Clears the requested warnlist
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     inline void clearList( const WebServer ws, const WarnlistField fld )
     { getList( ws, fld ).clear(); }
 
-    //! \throw BWlistException, DoNotCatchException
+    //! Adds the provided item to the requested warnlist
+    /*!
+        \throw BWlistException, DoNotCatchException
+    */
     inline void addItem( const WebServer ws, const WarnlistField fld, const std::string& item )
     { get( ws, fld ).add( item ); }
 
-    //! \throw BWlistException
+    //! Remove the requested item from the requested warnlist
+    /*!
+        \throw BWlistException
+    */
     inline void removeItem( const WebServer ws, const WarnlistField fld, const std::string& item )
     { get( ws, fld ).remove( item ); }
 
-    //! \throw BWlistException
+    //! Moves the requested item one position up in the requested warnlist
+    /*!
+        \throw BWlistException
+    */
     inline int moveUpItem( const WebServer ws, const WarnlistField fld, const std::string& item )
     { return get( ws, fld ).moveUp( item ); }
 
-    //! \throw BWlistException
+    //! Moves the requested item one position down in the requested warnlist
+    /*!
+        \throw BWlistException
+    */
     inline int moveDownItem( const WebServer ws, const WarnlistField fld, const std::string& item )
     { return get( ws, fld ).moveDown( item ); }
 };