iox-eclipse-iceoryx#1640 Update documentation

Signed-off-by: Matthias Killat <[email protected]>

.clang-tidy-diff-scans.txt

@@ -36,6 +36,14 @@
 ./iceoryx_hoofs/source/posix_wrapper/shared_memory_object/*
 ./iceoryx_hoofs/test/moduletests/test_posix*
 ./iceoryx_hoofs/include/iceoryx_hoofs/design_pattern/builder.hpp
+./iceoryx_hoofs/include/iceoryx_hoofs/design_pattern/polymorphic_handler.hpp
+./iceoryx_hoofs/include/iceoryx_hoofs/design_pattern/static_lifetime_guard.hpp
+
+./iceoryx_hoofs/include/iceoryx_hoofs/internal/design_pattern/polymorphic_handler.inl
+./iceoryx_hoofs/include/iceoryx_hoofs/internal/design_pattern/static_lifetime_guard.inl
+
+./iceoryx_hoofs/test/moduletests/test_polymorphic_handler.cpp
+./iceoryx_hoofs/test/moduletests/test_static_lifetime_guard.cpp
 
 ./iceoryx_hoofs/container/include/iox/**/*
 ./iceoryx_hoofs/test/moduletests/test_container_*

doc/design/polymorphic_handler.md

@@ -229,7 +229,7 @@ the worst thing that can happen is working with a outdated handler.
 
 This does not require blocking and only relies on fairly cheap atomic operations.
 Without using a mutex while using the handler, it is impossible that
-threads will always use the latest handler (as it maychange at any time).
+threads will always use the latest handler (as it may change at any time).
 However, this is not required, it only is required that a handler that is
 obtained can be safely accessed. The latter is ensured by using `StaticLifetimeGuard`.
 

iceoryx_hoofs/include/iceoryx_hoofs/design_pattern/polymorphic_handler.hpp

@@ -45,19 +45,21 @@ struct DefaultHooks
 } // namespace detail
 
 /// @brief Implements a singleton handler that has a default instance and can be changed
-///        to another instance at runtime. All instances have to derive from the same interface.
-///        The singleton handler owns the default instance but all other instances are created externally.
-/// @tparam Interface The interface of the handler instances. Must inherit from Activatable.
+/// to another instance at runtime. All instances have to derive from the same interface.
+/// The singleton handler owns the default instance but all other instances are created externally.
+/// @tparam Interface The interface of the handler instances.
 /// @tparam Default The type of the default instance. Must be equal to or derive from Interface.
+/// @tparam Hooks A struct that implements onSetAfterFinalize which is called when
+/// attempting to set or reset the handler after finalize was called.
 ///
 /// @note In the special case where Default equals Interface, no polymorphism is required.
-///       It is then possible to e.g. switch between multiple instances of Default type.
+/// It is then possible to e.g. switch between multiple instances of Default type.
 /// @note The lifetime of external non-default instances must exceed the lifetime of the PolymorphicHandler.
 /// @note The PolymorphicHandler is guaranteed to provide a valid handler during the whole program lifetime (static).
-///       It is hence not advisable to have other static variables depend on the PolymorphicHandler.
-///       It must be ensured that they are destroyed before the PolymorphicHandler.
+/// It is hence not advisable to have other static variables depend on the PolymorphicHandler.
+/// It must be ensured that they are destroyed before the PolymorphicHandler.
 /// @note Hooks must implement
-///       static void onSetAfterFinalize(Interface& /*currentInstance*/, Interface& /*newInstance*/).
+/// static void onSetAfterFinalize(Interface& /*currentInstance*/, Interface& /*newInstance*/).
 template <typename Interface, typename Default, typename Hooks = detail::DefaultHooks<Interface>>
 class PolymorphicHandler
 {

iceoryx_hoofs/include/iceoryx_hoofs/internal/design_pattern/polymorphic_handler.inl

@@ -50,9 +50,8 @@ void DefaultHooks<Interface>::onSetAfterFinalize(Interface&, Interface&) noexcep
 //    - sets m_current of instance to default instance (release)
 
 // 2. If any thread changes the handler with set or reset, it will:
-//    - be detected by
+//    - be detected by comparison with local handler
 //    - set the current handler to the new handler
-//    - deactivate the old handler (can still be used as it still needs to exist)
 //
 
 // On any call after the handler was changed in another thread