Documentation, commenting, canonicalisation

include/acestl/reactor/custom_event_handler.hpp

@@ -4,11 +4,11 @@
  * Purpose: Event handler class for custom event notifications.
  *
  * Created: 1st October 2004
- * Updated: 21st March 2025
+ * Updated: 15th October 2026
  *
  * Home:    http://stlsoft.org/
  *
- * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 2004-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -55,7 +55,7 @@
 # define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_MAJOR       2
 # define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_MINOR       1
 # define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_REVISION    13
-# define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_EDIT        47
+# define ACESTL_VER_ACESTL_REACTOR_HPP_CUSTOM_EVENT_HANDLER_EDIT        48
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -347,7 +347,7 @@ class custom_event_handler
      *
      * \return \c nullptr on failure, the event id on success
      *
-     * \remarks The custom event can be cancelled via cancel_custom_event()
+     * \note The custom event can be cancelled via cancel_custom_event().
      *
      * \note Custom events are "one-shot". When the event delay elapses and the
      * handle_custom_event() callback is called, the event has been deregistered from
@@ -365,7 +365,7 @@ class custom_event_handler
      *
      * \return \c nullptr on failure, the event id on success
      *
-     * \remarks The custom event can be cancelled via cancel_custom_event()
+     * \note The custom event can be cancelled via cancel_custom_event().
      *
      * \note Custom events are "one-shot". When the event delay elapses and the
      * handle_custom_event() callback is called, the event has been deregistered from

include/atlstl/automation/multiple_dispatch.hpp

@@ -5,11 +5,11 @@
  *              through multiple IDispatch interfaces visible to script clients.
  *
  * Created:     15th May 2006
- * Updated:     20th March 2025
+ * Updated:     15th October 2026
  *
  * Home:        http://stlsoft.org/
  *
- * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 2007-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -57,7 +57,7 @@
 # define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_MAJOR      2
 # define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_MINOR      1
 # define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_REVISION   5
-# define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_EDIT       30
+# define ATLSTL_VER_ATLSTL_AUTOMATION_HPP_MULTIPLE_DISPATCH_EDIT       31
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -214,7 +214,7 @@ class IDispatchImpl2
      * which has thus undertaken to interpret them. This stripe is then
      * detected
      *
-     * \remarks Names are matched en bloc: they are either all matched by one
+     * \note Names are matched en bloc: they are either all matched by one
      *  interface, or all by the other. It is <b>never</b> the case that
      *  some part are matched by one and the remainder by the other.
      *
@@ -274,7 +274,7 @@ class IDispatchImpl2
      * from which the appropriate dispiniterface is determined. The
      * stripe is then removed, and the method invoked.
      *
-     * \remarks Names are matched en bloc: they are either all matched by one
+     * \note Names are matched en bloc: they are either all matched by one
      *  interface, or all by the other. It is <b>never</b> the case that
      *  some part are matched by one and the remainder by the other.
      *
@@ -365,7 +365,7 @@ class IDispatchImpl3
      * which has thus undertaken to interpret them. This stripe is then
      * detected
      *
-     * \remarks Names are matched en bloc: they are either all matched by one
+     * \note Names are matched en bloc: they are either all matched by one
      *  interface, or all by the other. It is <b>never</b> the case that
      *  some part are matched by one and the remainder by the other.
      *
@@ -433,7 +433,7 @@ class IDispatchImpl3
      * from which the appropriate dispiniterface is determined. The
      * stripe is then removed, and the method invoked.
      *
-     * \remarks Names are matched en bloc: they are either all matched by one
+     * \note Names are matched en bloc: they are either all matched by one
      *  interface, or all by the other. It is <b>never</b> the case that
      *  some part are matched by one and the remainder by the other.
      *
@@ -540,7 +540,7 @@ class IDispatchImpl4
      * which has thus undertaken to interpret them. This stripe is then
      * detected
      *
-     * \remarks Names are matched en bloc: they are either all matched by one
+     * \note Names are matched en bloc: they are either all matched by one
      *  interface, or all by the other. It is <b>never</b> the case that
      *  some part are matched by one and the remainder by the other.
      *
@@ -616,7 +616,7 @@ class IDispatchImpl4
      * from which the appropriate dispiniterface is determined. The
      * stripe is then removed, and the method invoked.
      *
-     * \remarks Names are matched en bloc: they are either all matched by one
+     * \note Names are matched en bloc: they are either all matched by one
      *  interface, or all by the other. It is <b>never</b> the case that
      *  some part are matched by one and the remainder by the other.
      *

include/comstl/collections/collection_sequence.hpp

@@ -4,15 +4,15 @@
  * Purpose:  STL sequence for COM collection interfaces.
  *
  * Created:  17th September 1998
- * Updated:  20th March 2025
+ * Updated:  15th October 2026
  *
  * Thanks:   To Eduardo Bezerra and Vivi Orunitia for reporting
  *           incompatibilities with Borland's 5.82 (Turbo C++). The awful
  *           preprocessor hack around retrievalQuanta are the result. ;)
  *
  * Home:     http://stlsoft.org/
  *
- * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 1998-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -59,7 +59,7 @@
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_MAJOR    6
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_MINOR    1
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_REVISION 19
-# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_EDIT     126
+# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_COLLECTION_SEQUENCE_EDIT     127
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -185,7 +185,7 @@ typedef collection_sequence<
  * \note The iterator instances returned by begin() and end() are valid outside
  *   the lifetime of the collection instance from which they are obtained
  *
- * \remarks A detailed examination of the design and implementation of this
+ * \note A detailed examination of the design and implementation of this
  *   class template is described in Chapters 28 and 29 of
  *   <a href="http://www.extendedstl.com/"><b>Extended STL, volume 1</b></a>
  *   (published by Addison-Wesley, June 2007).

include/comstl/collections/enumeration_policies.hpp

@@ -4,11 +4,11 @@
  * Purpose: Policies for enumerator interface handling.
  *
  * Created: 20th December 2003
- * Updated: 21st March 2025
+ * Updated: 15th October 2026
  *
  * Home:    http://stlsoft.org/
  *
- * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 2003-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -54,7 +54,7 @@
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MAJOR       6
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_MINOR       1
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_REVISION    16
-# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_EDIT        76
+# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATION_POLICIES_EDIT        77
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -205,7 +205,7 @@ struct input_cloning_policy
 public:
     /// Gets a working "copy" of the given enumerator root
     ///
-    /// \remarks For this policy, this simply calls AddRef()
+    /// \note For this policy, this simply calls AddRef().
     static interface_type *get_working_instance(interface_type *root)
     {
         COMSTL_ASSERT(NULL != root);
@@ -254,7 +254,7 @@ struct cloneable_cloning_policy
 public:
     /// Gets a working "copy" of the given enumerator root
     ///
-    /// \remarks For this policy, this calls Clone(), and returns \c nullptr
+    /// \note For this policy, this calls Clone(), and returns \c nullptr
     ///   if that fails.
     static interface_type *get_working_instance(interface_type *root)
     {
@@ -324,7 +324,7 @@ struct forward_cloning_policy
 public:
     /// Gets a working "copy" of the given enumerator root
     ///
-    /// \remarks For this policy, this calls Clone(), and throws an
+    /// \note For this policy, this calls Clone(), and throws an
     ///   instance of comstl::clone_failure if that fails (or returns
     ///   \c nullptr if exception support is disabled).
     static interface_type *get_working_instance(interface_type *root)
@@ -443,7 +443,7 @@ struct policy_adaptor
  *
  * \ingroup group__library__Collection
  *
- * \remarks Invokes the the get__NewEnum() method
+ * \note Invokes the the get__NewEnum() method.
  */
 template <ss_typename_param_k CI>
 struct new_enum_property_policy
@@ -475,7 +475,7 @@ struct new_enum_property_policy
  *
  * \ingroup group__library__Collection
  *
- * \remarks Invokes the the _NewEnum() method
+ * \note Invokes the the _NewEnum() method.
  */
 template <ss_typename_param_k CI>
 struct new_enum_method_policy
@@ -497,7 +497,7 @@ struct new_enum_method_policy
  *
  * \ingroup group__library__Collection
  *
- * \remarks Calls IDispatch::Invoke(DISPID_NEWENUM, . . . , DISPATCH_METHOD | DISPATCH_PROPERTYGET, . . . );
+ * \note Calls IDispatch::Invoke(DISPID_NEWENUM, . . . , DISPATCH_METHOD | DISPATCH_PROPERTYGET, . . . );
  */
 template <ss_typename_param_k CI>
 struct new_enum_by_dispid_policy

include/comstl/collections/enumerator_sequence.hpp

@@ -4,15 +4,15 @@
  * Purpose: STL sequence for IEnumXXXX enumerator interfaces.
  *
  * Created: 17th September 1998
- * Updated: 20th March 2025
+ * Updated: 15th October 2026
  *
  * Thanks:  To Eduardo Bezerra and Vivi Orunitia for reporting
  *          incompatibilities with Borland's 5.82 (Turbo C++). The awful
  *          preprocessor hack around retrievalQuanta are the result. ;)
  *
  * Home:    http://stlsoft.org/
  *
- * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 1998-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -59,7 +59,7 @@
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_MAJOR    6
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_MINOR    1
 # define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_REVISION 15
-# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_EDIT     280
+# define COMSTL_VER_COMSTL_COLLECTIONS_HPP_ENUMERATOR_SEQUENCE_EDIT     281
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -186,7 +186,7 @@ std::for_each(guids.begin(), guids.end(), dump_GUID);
  * \note The iterator instances returned by begin() and end() are valid outside
  * the lifetime of the collection instance from which they are obtained
  *
- * \remarks A detailed examination of the design and implementation of this
+ * \note A detailed examination of the design and implementation of this
  *   class template is described in Chapters 28 and 29 of
  *   <a href="http://www.extendedstl.com/"><b>Extended STL, volume 1</b></a>
  *   (published by Addison-Wesley, June 2007).

include/comstl/exception/variant_type_exception.hpp

@@ -4,11 +4,11 @@
  * Purpose: COM-related exception classes, and their policy classes
  *
  * Created: 8th December 2004
- * Updated: 20th March 2025
+ * Updated: 15th October 2026
  *
  * Home:    http://stlsoft.org/
  *
- * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 2004-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -55,7 +55,7 @@
 # define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_MAJOR       3
 # define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_MINOR       0
 # define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_REVISION    5
-# define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_EDIT        61
+# define COMSTL_VER_COMSTL_EXCEPTION_HPP_VARIANT_TYPE_EXCEPTION_EDIT        62
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -103,7 +103,7 @@ namespace comstl_project
  *
  * \ingroup group__library__Exception
  *
- * \remarks This is thrown by comstl::safearray_sequence on variant type
+ * \note This is thrown by comstl::safearray_sequence on variant type
  *   mismatches.
  */
 class variant_type_exception

include/comstl/util/object_functions.h

@@ -4,11 +4,11 @@
  * Purpose: Reference-counting helper functions.
  *
  * Created: 2nd March 1996
- * Updated: 24th December 2024
+ * Updated: 15th October 2026
  *
  * Home:    http://stlsoft.org/
  *
- * Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 1996-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -54,7 +54,7 @@
 # define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_MAJOR    3
 # define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_MINOR    2
 # define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_REVISION 1
-# define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_EDIT     81
+# define COMSTL_VER_COMSTL_UTIL_H_OBJECT_FUNCTIONS_EDIT     82
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -108,7 +108,7 @@ namespace comstl_project
  *
  * \pre \c p is a \c nullptr pointer, or a valid pointer to a COM interface.
  *
- * \remarks If the function success, the caller must release the reference
+ * \note If the function success, the caller must release the reference
  *   count associated with the interface pointer in \c *identity.
  *
  * \note Intended for use in C-compilation units only. For C++, use
@@ -306,7 +306,7 @@ namespace comstl
  *
  * \pre \c p is a \c nullptr pointer, or a valid pointer to a COM interface.
  *
- * \remarks If the function success, the caller must release the reference
+ * \note If the function success, the caller must release the reference
  *   count associated with the interface pointer in \c *identity.
  *
  * \note Implemented in terms of the C-compatible function

include/comstl/util/variant.hpp

@@ -4,11 +4,11 @@
  * Purpose: variant class.
  *
  * Created: 12th December 1996
- * Updated: 20th March 2025
+ * Updated: 15th October 2026
  *
  * Home:    http://stlsoft.org/
  *
- * Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
+ * Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
  * Copyright (c) 1996-2019, Matthew Wilson and Synesis Software
  * All rights reserved.
  *
@@ -54,7 +54,7 @@
 # define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_MAJOR       2
 # define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_MINOR       3
 # define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_REVISION    15
-# define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_EDIT        180
+# define _COMSTL_VER_COMSTL_UTIL_HPP_COMSTL_VARIANT_EDIT        181
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -127,7 +127,7 @@ namespace comstl_project
  *
  * \ingroup group__library__COM_Utility
  *
- * \remarks comstl::variant publicly derives from \c VARIANT as a measure of
+ * \note comstl::variant publicly derives from \c VARIANT as a measure of
  *   expedience, rather than as an act of design sophistication. Any manual
  *   manipulation of the instances, or their member variables, is at the
  *   user's risk. Notwithstanding, this is helped by the fact that

include/inetstl/util/uds_helpers.h

@@ -4,7 +4,7 @@
  * Purpose: Unix Domain Sockets helper functions
  *
  * Created: 21st February 2025
- * Updated: 29th May 2025
+ * Updated: 15th October 2026
  *
  * Home:    http://stlsoft.org/
  *
@@ -53,7 +53,7 @@
 # define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_MAJOR       1
 # define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_MINOR       0
 # define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_REVISION    2
-# define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_EDIT        4
+# define INETSTL_VER_INETSTL_UTIL_H_UDS_HELPERS_EDIT        5
 #endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */
 
 
@@ -159,7 +159,7 @@ inetstl_c_sockaddr_un_init_from_path(
          * - on macOS, `sockaddr_un` has field `sun_len`, which is not
          *   present on Linux;
          * - the field `sun_path` has a fixed size (of 104, or 108, or ...),
-         *   and there are some differences in whether a NUL-terminator is
+         *   and there are some differences in whether a NUL character is
          *   required, hence if the path length is exactly the same as the
          *   available fixed space then there is an issue;
          *