Errata: Update comments and documentation.

Author: SolidWallOfCode

Diff for: code/include/swoc/Errata.h

@@ -226,6 +226,7 @@ class Errata {
    *
    * The error code is set to the default.
    * @a text is localized to @a this and does not need to be persistent.
+   * The severity is updated to @a severity if the latter is more severe.
    */
   self_type &note(Severity severity, std::string_view text);
 
@@ -254,6 +255,8 @@ class Errata {
    * This is a unified interface for other fixed text @c note methods which all forward to this
    * method. If @a severity does not have a value then the annotation is never filtered.
    *
+   * The severity is updated to @a severity if the latter is set and more severe.
+   *
    * @see FILTER_SEVERITY
    */
   self_type &note_s(std::optional<Severity> severity, std::string_view text);
@@ -280,6 +283,8 @@ class Errata {
    * @param fmt Format string (@c BufferWriter style).
    * @param args Arguments for values in @a fmt.
    * @return A reference to this object.
+   *
+   * The severity is updated to @a severity if the latter is more severe.
    */
   template <typename... Args> self_type &note(Severity severity, std::string_view fmt, Args &&... args);
 
@@ -291,6 +296,8 @@ class Errata {
    *
    * This is intended for use by external "helper" methods that pass their own arguments to this
    * using @c forward_as_tuple.
+   *
+   * The severity is updated to @a severity if the latter is more severe.
    */
   template <typename... Args> self_type &note_v(Severity severity, std::string_view fmt, std::tuple<Args...> const &args);
 
@@ -300,6 +307,8 @@ class Errata {
    * @param args Arguments for values in @a fmt.
    * @return A reference to this object.
    *
+   * The severity is updated to @a severity if the latter is set and more severe.
+   *
    * This the effective implementation method for all variadic styles of the @a note method.
    */
   template <typename... Args>
@@ -405,6 +414,9 @@ class Errata {
   /// The code for the top message.
   code_type const &code() const;
 
+  /// Set the @a code for @a this.
+  self_type & assign(code_type code);
+
   /// Number of messages in the errata.
   size_t length() const;
 
@@ -916,6 +928,11 @@ Errata::code() const -> code_type const & {
   return this->empty() ? DEFAULT_CODE : _data->_code;
 }
 
+inline auto Errata::assign(code_type code) -> self_type & {
+  this->data()->_code = code;
+  return *this;
+}
+
 inline auto
 Errata::severity() const -> Severity {
   return _data ? _data->_severity : DEFAULT_SEVERITY;

Diff for: doc/code/Errata.en.rst

@@ -119,15 +119,16 @@ The initialization is done in :code:`test_Errata_init` which is called from :cod
 
 If there is no external initialization, then there are three levels of severity 0..2 with
 the names "Info", "Warning", and "Error". The default severity is "Error" (2) with a failure threshold
-of 2.
+of 2 ("Error").
 
 By default annotations do not have a severity, that is a property of the :code:`Errata`. However a
-severity can be added to an annotation. This has no effect on the severity of the :code:`Errata` and
-is intended purely for display and filtering. The latter can be done by adjusting the value of
-:code:`swoc::Errata::FILTER_SEVERITY`. If a severity is provided with an annotation (via some variant
-of the :code:`note` method) then this is checked against :code:`FILTER_SEVERITY` and if it is less
-than that the annotation is not added. This enables an application to dynamically control the
-verbosity of errors without changing how they are generated.
+severity can be added to an annotation. If this is done the the severity of the :code:`Errata` is
+updated to that severity if it is larger (more severe) than the current severity. Annotations can be
+filtered by adjusting the value of :code:`swoc::Errata::FILTER_SEVERITY`. If a severity is provided
+with an annotation (via some variant of the :code:`note` method) then this is checked against
+:code:`FILTER_SEVERITY` and if it is less than that the annotation is not added. This enables an
+application to dynamically control the verbosity of errors without changing how they are generated.
+The :code:`Errata` serverity is updated as appropriate even if the annotation is discarded.
 
 Examples
 ========