merged AI doc, some new pages

libs/main/core/piobject_macros.h

@@ -1,9 +1,17 @@
-/*! \file piobject_macros.h
- * \ingroup Core
- * \~\brief
- * \~english PIObject macros
- * \~russian Макросы PIObject
- */
+//! \~\ingroup Core
+//! \~\file piobject_macros.h
+//! \~\brief
+//! \~english PIObject macros for event system and object introspection
+//! \~russian Макросы PIObject для событийной системы и интроспекции объектов
+//! \~\details
+//! \~english
+//! This file declares the macro layer used by %PIObject-based classes:
+//! class registration, event declaration, event handler declaration,
+//! connection helpers and event raising helpers.
+//! \~russian
+//! Этот файл объявляет макросный слой для классов на базе %PIObject:
+//! регистрацию класса, объявление событий, объявление обработчиков,
+//! макросы соединения и макросы вызова событий.
 /*
     PIP - Platform Independent Primitives
     Macros for PIObject
@@ -32,47 +40,47 @@
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english You should use this macro after class declaration to use EVENT and EVENT_HANDLER and correct piCoutObj output
-//! \~russian Необходимо использовать этот макрос после объявления класса для использования событийной системы и корректного вывода
-//! piCoutObj
+//! \~english Put this macro inside a direct %PIObject subclass definition to enable registered events, event handlers and class metadata.
+//! \~russian Поместите этот макрос внутрь объявления прямого наследника %PIObject, чтобы включить регистрацию событий, обработчиков и
+//! метаданных класса.
 #  define PIOBJECT(name)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english You should use this macro after class declaration to use EVENT and EVENT_HANDLER of parent class, and \a scopeList()
-//! \~russian
+//! \~english Put this macro inside a %PIObject subclass definition to inherit registered methods and class scope from "parent".
+//! \~russian Поместите этот макрос внутрь объявления наследника %PIObject, чтобы унаследовать зарегистрированные методы и цепочку
+//! классов от "parent".
 #  define PIOBJECT_SUBCLASS(name, parent)
 
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event handler with name \"name\" and return type \"ret\", ret name()
-//! \~russian Объявляет обработчик событий с именем \"name\" и возвращаемым типом \"ret\", ret name()
+//! \~english Declare a registered event handler method with signature `ret name()`.
+//! \~russian Объявляет зарегистрированный метод-обработчик событий с сигнатурой `ret name()`.
 #  define EVENT_HANDLER0(ret, name)                                        ret name()
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event handler with name \"name\" and return type \"ret\", ret name(type0 var0)
-//! \~russian Объявляет обработчик событий с именем \"name\" и возвращаемым типом \"ret\", ret name(type0 var0)
+//! \~english Declare a registered event handler method with one argument.
+//! \~russian Объявляет зарегистрированный метод-обработчик событий с одним аргументом.
 #  define EVENT_HANDLER1(ret, name, type0, var0)                           ret name(type0 var0)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event handler with name \"name\" and return type \"ret\", ret name(type0 var0, type1 var1)
-//! \~russian Объявляет обработчик событий с именем \"name\" и возвращаемым типом \"ret\", ret name(type0 var0, type1 var1)
+//! \~english Declare a registered event handler method with two arguments.
+//! \~russian Объявляет зарегистрированный метод-обработчик событий с двумя аргументами.
 #  define EVENT_HANDLER2(ret, name, type0, var0, type1, var1)              ret name(type0 var0, type1 var1)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event handler with name \"name\" and return type \"ret\", ret name(type0 var0, type1 var1, type2 var2)
-//! \~russian Объявляет обработчик событий с именем \"name\" и возвращаемым типом \"ret\", ret name(type0 var0, type1 var1, type2 var2)
+//! \~english Declare a registered event handler method with three arguments.
+//! \~russian Объявляет зарегистрированный метод-обработчик событий с тремя аргументами.
 #  define EVENT_HANDLER3(ret, name, type0, var0, type1, var1, type2, var2) ret name(type0 var0, type1 var1, type2 var2)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event handler with name \"name\" and return type \"ret\", ret name(type0 var0, type1 var1, type2 var2, type3 var3)
-//! \~russian Объявляет обработчик событий с именем \"name\" и возвращаемым типом \"ret\", ret name(type0 var0, type1 var1, type2 var2,
-//! type3 var3)
+//! \~english Declare a registered event handler method with four arguments.
+//! \~russian Объявляет зарегистрированный метод-обработчик событий с четырьмя аргументами.
 #  define EVENT_HANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) \
 	  ret name(type0 var0, type1 var1, type2 var2, type3 var3)
 
@@ -85,36 +93,32 @@
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare virtual event handler with name \"name\" and return type \"ret\", virtual ret name()
-//! \~russian Объявляет виртуальный обработчик событий с именем \"name\" и возвращаемым типом \"ret\", virtual ret name()
+//! \~english Declare a virtual registered event handler method with signature `virtual ret name()`.
+//! \~russian Объявляет виртуальный зарегистрированный метод-обработчик с сигнатурой `virtual ret name()`.
 #  define EVENT_VHANDLER0(ret, name)                                        virtual ret name()
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare virtual event handler with name \"name\" and return type \"ret\", virtual ret name(type0 var0)
-//! \~russian Объявляет виртуальный обработчик событий с именем \"name\" и возвращаемым типом \"ret\", virtual ret name(type0 var0)
+//! \~english Declare a virtual registered event handler method with one argument.
+//! \~russian Объявляет виртуальный зарегистрированный метод-обработчик с одним аргументом.
 #  define EVENT_VHANDLER1(ret, name, type0, var0)                           virtual ret name(type0 var0)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare virtual event handler with name \"name\" and return type \"ret\", virtual ret name(type0 var0, type1 var1)
-//! \~russian Объявляет виртуальный обработчик событий с именем \"name\" и возвращаемым типом \"ret\", virtual ret name(type0 var0, type1
-//! var1)
+//! \~english Declare a virtual registered event handler method with two arguments.
+//! \~russian Объявляет виртуальный зарегистрированный метод-обработчик с двумя аргументами.
 #  define EVENT_VHANDLER2(ret, name, type0, var0, type1, var1)              virtual ret name(type0 var0, type1 var1)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare virtual event handler with name \"name\" and return type \"ret\", virtual ret name(type0 var0, type1 var1, type2 var2)
-//! \~russian Объявляет виртуальный обработчик событий с именем \"name\" и возвращаемым типом \"ret\", virtual ret name(type0 var0, type1
-//! var1, type2 var2)
+//! \~english Declare a virtual registered event handler method with three arguments.
+//! \~russian Объявляет виртуальный зарегистрированный метод-обработчик с тремя аргументами.
 #  define EVENT_VHANDLER3(ret, name, type0, var0, type1, var1, type2, var2) virtual ret name(type0 var0, type1 var1, type2 var2)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare virtual event handler with name \"name\" and return type \"ret\", virtual ret name(type0 var0, type1 var1, type2 var2,
-//! type3 var3)
-//! \~russian Объявляет виртуальный обработчик событий с именем \"name\" и возвращаемым типом \"ret\", virtual ret name(type0 var0, type1
-//! var1, type2 var2, type3 var3)
+//! \~english Declare a virtual registered event handler method with four arguments.
+//! \~russian Объявляет виртуальный зарегистрированный метод-обработчик с четырьмя аргументами.
 #  define EVENT_VHANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) \
 	  virtual ret name(type0 var0, type1 var1, type2 var2, type3 var3)
 
@@ -127,32 +131,32 @@
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event with name \"name\", void name();
-//! \~russian Объявляет событие с именем \"name\", void name();
+//! \~english Declare an event method with no arguments.
+//! \~russian Объявляет метод-событие без аргументов.
 #  define EVENT0(name)                                                     void name();
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event with name \"name\", void name(type0 var0);
-//! \~russian Объявляет событие с именем \"name\", void name(type0 var0);
+//! \~english Declare an event method with one argument.
+//! \~russian Объявляет метод-событие с одним аргументом.
 #  define EVENT1(name, type0, var0)                                        void name(type0 var0);
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event with name \"name\", void name(type0 var0, type1 var1);
-//! \~russian Объявляет событие с именем \"name\", void name(type0 var0, type1 var1);
+//! \~english Declare an event method with two arguments.
+//! \~russian Объявляет метод-событие с двумя аргументами.
 #  define EVENT2(name, type0, var0, type1, var1)                           void name(type0 var0, type1 var1);
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event with name \"name\", void name(type0 var0, type1 var1, type2 var2);
-//! \~russian Объявляет событие с именем \"name\", void name(type0 var0, type1 var1, type2 var2);
+//! \~english Declare an event method with three arguments.
+//! \~russian Объявляет метод-событие с тремя аргументами.
 #  define EVENT3(name, type0, var0, type1, var1, type2, var2)              void name(type0 var0, type1 var1, type2 var2);
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Declare event with name \"name\", void name(type0 var0, type1 var1, type2 var2, type3 var3);
-//! \~russian Объявляет событие с именем \"name\", void name(type0 var0, type1 var1, type2 var2, type3 var3);
+//! \~english Declare an event method with four arguments.
+//! \~russian Объявляет метод-событие с четырьмя аргументами.
 #  define EVENT4(name, type0, var0, type1, var1, type2, var2, type3, var3) void name(type0 var0, type1 var1, type2 var2, type3 var3);
 
 //! \relatesalso PIObject
@@ -162,10 +166,26 @@
 #  define EVENT                                                            EVENT0
 
 
+//! \relatesalso PIObject
+//! \~\brief
+//! \~english Compatibility helper that raises event "event" on source object "src".
+//! \~russian Совместимый вспомогательный макрос, вызывающий событие "event" у объекта-источника "src".
 #  define RAISE_EVENT0(src, event)
+//! \relatesalso PIObject
+//! \~english Compatibility helper that raises event "event" with one argument.
+//! \~russian Совместимый вспомогательный макрос, вызывающий событие "event" с одним аргументом.
 #  define RAISE_EVENT1(src, event, v0)
+//! \relatesalso PIObject
+//! \~english Compatibility helper that raises event "event" with two arguments.
+//! \~russian Совместимый вспомогательный макрос, вызывающий событие "event" с двумя аргументами.
 #  define RAISE_EVENT2(src, event, v0, v1)
+//! \relatesalso PIObject
+//! \~english Compatibility helper that raises event "event" with three arguments.
+//! \~russian Совместимый вспомогательный макрос, вызывающий событие "event" с тремя аргументами.
 #  define RAISE_EVENT3(src, event, v0, v1, v2)
+//! \relatesalso PIObject
+//! \~english Compatibility helper that raises event "event" with four arguments.
+//! \~russian Совместимый вспомогательный макрос, вызывающий событие "event" с четырьмя аргументами.
 #  define RAISE_EVENT4(src, event, v0, v1, v2, v3)
 #  define RAISE_EVENT RAISE_EVENT0
 
@@ -176,11 +196,11 @@
 //! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" объекта \"dest\".
 //! \~\details
 //! \~english
-//! \"handler\" can handle subset arguments of \"event\".
-//! Returns \a PIObject::Connection
+//! \"handler\" can accept a prefix of \"event\" arguments.
+//! This macro resolves registered methods by name at run time and returns \a PIObject::Connection.
 //! \~russian
-//! \"handler\" может принимать не все аргументы от \"event\".
-//! Возвращает \a PIObject::Connection
+//! \"handler\" может принимать только начальную часть аргументов \"event\".
+//! Макрос ищет зарегистрированные методы по имени во время выполнения и возвращает \a PIObject::Connection.
 #  define CONNECTU(src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -189,17 +209,19 @@
 //! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" объекта \"dest\".
 //! \~\details
 //! \~english
-//! \"handler\" can handle subset arguments of \"event\".
-//! Event handler will be executed by \"performer\" when \a PIObject::callQueuedEvents() called.
+//! \"handler\" can accept a prefix of \"event\" arguments.
+//! Delivery is queued on the performer object and runs only when that object calls
+//! \a PIObject::callQueuedEvents() or \a PIObject::maybeCallQueuedEvents().
 //! All argument types should be registered by \a REGISTER_VARIANT() macro, but many
 //! common and PIP types already done.
-//! Returns \a PIObject::Connection
+//! Returns \a PIObject::Connection.
 //! \~russian
-//! \"handler\" может принимать не все аргументы от \"event\".
-//! Обработчик будет вызван объектом \"performer\" при вызове \a PIObject::callQueuedEvents().
+//! \"handler\" может принимать только начальную часть аргументов \"event\".
+//! Доставка ставится в очередь объекта \"performer\" и выполняется только когда этот объект
+//! вызывает \a PIObject::callQueuedEvents() или \a PIObject::maybeCallQueuedEvents().
 //! Все типы аргументов должны быть зарегистрированы с помощью макроса \a REGISTER_VARIANT(),
 //! однако многие стандартные и PIP типы уже там.
-//! Возвращает \a PIObject::Connection
+//! Возвращает \a PIObject::Connection.
 #  define CONNECTU_QUEUED(src, event, dest, handler, performer)
 
 //! \relatesalso PIObject
@@ -208,13 +230,13 @@
 //! \~russian Соединяет событие \"event\" объекта \"src\" к лямбда-функции \"functor\".
 //! \~\details
 //! \~english
-//! \"event\" and \"functor\" must has equal argument lists.
-//! You should parentness \"functor\" with () if this is complex lambda.
-//! Returns \a PIObject::Connection
+//! \"event\" and \"functor\" must have the same argument list.
+//! Wrap \"functor\" in () when the lambda expression is complex.
+//! Returns \a PIObject::Connection.
 //! \~russian
-//! \"event\" и \"functor\" должны иметь одинаковые аргументы.
-//! В случае сложной лямбда-функции оберните её ().
-//! Возвращает \a PIObject::Connection
+//! \"event\" и \"functor\" должны иметь одинаковый список аргументов.
+//! В случае сложной лямбда-функции оберните её в ().
+//! Возвращает \a PIObject::Connection.
 #  define CONNECTL(src, event, functor)
 
 //! \relatesalso PIObject
@@ -222,12 +244,11 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" with
-//! check of event and handler exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" с проверкой наличия события и обработчика.
+//! \~english Legacy compatibility helper that connects an event to a registered handler with compile-time signature spelling.
+//! \~russian Устаревший совместимый макрос, который соединяет событие с зарегистрированным обработчиком через явное указание сигнатуры.
 //! \~\details
-//! Returns PIObject::Connection
+//! \~english Prefer \a CONNECTU() for new code.
+//! \~russian Для нового кода предпочитайте \a CONNECTU().
 #  define CONNECT0(ret, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -235,12 +256,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" with
-//! check of event and handler exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" с проверкой наличия события и обработчика.
-//! \~\details
-//! Returns PIObject::Connection
+//! \~english Legacy compatibility helper for a one-argument registered event or handler.
+//! \~russian Устаревший совместимый макрос для зарегистрированного события или обработчика с одним аргументом.
 #  define CONNECT1(ret, type0, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -248,12 +265,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" with
-//! check of event and handler exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" с проверкой наличия события и обработчика.
-//! \~\details
-//! Returns PIObject::Connection
+//! \~english Legacy compatibility helper for a two-argument registered event or handler.
+//! \~russian Устаревший совместимый макрос для зарегистрированного события или обработчика с двумя аргументами.
 #  define CONNECT2(ret, type0, type1, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -261,12 +274,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" with
-//! check of event and handler exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" с проверкой наличия события и обработчика.
-//! \~\details
-//! Returns PIObject::Connection
+//! \~english Legacy compatibility helper for a three-argument registered event or handler.
+//! \~russian Устаревший совместимый макрос для зарегистрированного события или обработчика с тремя аргументами.
 #  define CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -274,12 +283,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" with
-//! check of event and handler exists.
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" с проверкой наличия события и обработчика.
-//! \~\details
-//! Returns PIObject::Connection
+//! \~english Legacy compatibility helper for a four-argument registered event or handler.
+//! \~russian Устаревший совместимый макрос для зарегистрированного события или обработчика с четырьмя аргументами.
 #  define CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -297,10 +302,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" without
-//! check of event exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" без проверки наличия события и обработчика.
+//! \~english Legacy compatibility helper that skips source method verification.
+//! \~russian Устаревший совместимый макрос, который пропускает проверку исходного метода.
 #  define WEAK_CONNECT0(ret, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -308,10 +311,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" without
-//! check of event exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" без проверки наличия события и обработчика.
+//! \~english Legacy compatibility helper that skips source method verification for one argument.
+//! \~russian Устаревший совместимый макрос, который пропускает проверку исходного метода для случая с одним аргументом.
 #  define WEAK_CONNECT1(ret, type0, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -319,10 +320,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" without
-//! check of event exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" без проверки наличия события и обработчика.
+//! \~english Legacy compatibility helper that skips source method verification for two arguments.
+//! \~russian Устаревший совместимый макрос, который пропускает проверку исходного метода для случая с двумя аргументами.
 #  define WEAK_CONNECT2(ret, type0, type1, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -330,10 +329,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" without
-//! check of event exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" без проверки наличия события и обработчика.
+//! \~english Legacy compatibility helper that skips source method verification for three arguments.
+//! \~russian Устаревший совместимый макрос, который пропускает проверку исходного метода для случая с тремя аргументами.
 #  define WEAK_CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -341,10 +338,8 @@
 //! \~english Use \a CONNECTU() instead
 //! \~russian Используйте \a CONNECTU()
 //! \~\brief
-//! \~english Connect event \"event\" from object \"src\" to event handler \"handler\" with return type \"ret\" from object \"dest\" without
-//! check of event exists
-//! \~russian Соединяет событие \"event\" объекта \"src\" к обработчику или событию \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\" без проверки наличия события и обработчика.
+//! \~english Legacy compatibility helper that skips source method verification for four arguments.
+//! \~russian Устаревший совместимый макрос, который пропускает проверку исходного метода для случая с четырьмя аргументами.
 #  define WEAK_CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -359,37 +354,32 @@
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english piDisconnect event \"event\" from object \"src\" from event handler \"handler\" with return type \"ret\" from object \"dest\"
-//! \~russian piDisconnect событие \"event\" объекта \"src\" от обработчика или события \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\"
+//! \~english Disconnect a registered event from a registered event handler.
+//! \~russian Разрывает соединение зарегистрированного события с зарегистрированным обработчиком.
 #  define DISCONNECT0(ret, src, event, dest, handler)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english piDisconnect event \"event\" from object \"src\" from event handler \"handler\" with return type \"ret\" from object \"dest\"
-//! \~russian piDisconnect событие \"event\" объекта \"src\" от обработчика или события \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\"
+//! \~english Disconnect a one-argument registered event from a registered event handler.
+//! \~russian Разрывает соединение зарегистрированного события с одним аргументом и зарегистрированного обработчика.
 #  define DISCONNECT1(ret, type0, src, event, dest, handler)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english piDisconnect event \"event\" from object \"src\" from event handler \"handler\" with return type \"ret\" from object \"dest\"
-//! \~russian piDisconnect событие \"event\" объекта \"src\" от обработчика или события \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\"
+//! \~english Disconnect a two-argument registered event from a registered event handler.
+//! \~russian Разрывает соединение зарегистрированного события с двумя аргументами и зарегистрированного обработчика.
 #  define DISCONNECT2(ret, type0, type1, src, event, dest, handler)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english piDisconnect event \"event\" from object \"src\" from event handler \"handler\" with return type \"ret\" from object \"dest\"
-//! \~russian piDisconnect событие \"event\" объекта \"src\" от обработчика или события \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\"
+//! \~english Disconnect a three-argument registered event from a registered event handler.
+//! \~russian Разрывает соединение зарегистрированного события с тремя аргументами и зарегистрированного обработчика.
 #  define DISCONNECT3(ret, type0, type1, type2, src, event, dest, handler)
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english piDisconnect event \"event\" from object \"src\" from event handler \"handler\" with return type \"ret\" from object \"dest\"
-//! \~russian piDisconnect событие \"event\" объекта \"src\" от обработчика или события \"handler\" с возвращаемым типом \"ret\" объекта
-//! \"dest\"
+//! \~english Disconnect a four-argument registered event from a registered event handler.
+//! \~russian Разрывает соединение зарегистрированного события с четырьмя аргументами и зарегистрированного обработчика.
 #  define DISCONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
 
 //! \relatesalso PIObject
@@ -401,8 +391,8 @@
 
 //! \relatesalso PIObject
 //! \~\brief
-//! \~english Returns pointer to events handler \"handler\"
-//! \~russian Возвращает указатель на обработчик события \"handler\"
+//! \~english Low-level helper that expands to the registered handler entry point.
+//! \~russian Низкоуровневый вспомогательный макрос, который разворачивается в точку входа зарегистрированного обработчика.
 #  define HANDLER(handler)