more ai generated doc with human review

2026-02-28 12:29:00 +03:00
parent 077f12c9e5
commit 0878891cd8
86 changed files with 2215 additions and 637 deletions
--- a/libs/main/io_devices/piconfig.h
+++ b/libs/main/io_devices/piconfig.h
@@ -1,9 +1,13 @@
-/*! \file piconfig.h
- * \ingroup IO
- * \~\brief
- * \~english Configuration files parser and writer
- * \~russian Разбор и запись конфигурационных файлов
- */
+//! \addtogroup IO
+//! \{
+//! \file piconfig.h
+//! \brief Configuration files parser and writer
+//! \~english Parser and writer for configuration files with tree structure support
+//! \~russian Разбор и запись конфигурационных файлов с поддержкой древовидной структуры
+//! \details
+//! \~english PIConfig provides functionality to read, write and manipulate configuration files in a tree-like structure.
+//! \~russian PIConfig предоставляет функциональность для чтения, записи и управления конфигурационными файлами в древовидной структуре.
+//! \}
 /*
    PIP - Platform Independent Primitives
    Configuration parser and writer
@@ -58,6 +62,8 @@
 	Entry & getValue(const PIString & vname, const double def, bool * exists = 0) const {return getValue(vname, PIString::fromNumber(def), exists);}
 // clang-format on

+//! \~english Main configuration parser and writer class
+//! \~russian Главный класс для разбора и записи конфигурационных файлов
 class PIP_EXPORT PIConfig {
 	friend class Entry;
 	friend class Branch;
@@ -79,6 +85,8 @@ public:
 	class Entry;


+	//! \~english Branch class - container for Entry objects
+	//! \~russian Класс Branch - контейнер для объектов Entry
 	class PIP_EXPORT Branch: public PIVector<Entry *> {
 		friend class PIConfig;
 		friend class Entry;
@@ -90,22 +98,44 @@ public:
 	public:
 		Branch() { ; }

+		//! \~english Get value from branch by name with default value
+		//! \~russian Получить значение из ветки по имени со значением по умолчанию
 		Entry & getValue(const PIString & vname, const PIString & def = PIString(), bool * exists = 0);
 		Entry & getValue(const PIString & vname, const PIString & def = PIString(), bool * exists = 0) const {
 			return const_cast<Branch *>(this)->getValue(vname, def, exists);
 		}
 		PICONFIG_GET_VALUE

+		//! \~english Get all leaf entries from the entire tree
+		//! \~russian Получить все листовые записи из всего дерева
 		Branch allLeaves();
+
+		//! \~english Get all entries with name containing specified substring
+		//! \~russian Получить все записи с именем, содержащим указанную подстроку
 		Branch getValues(const PIString & name);
+
+		//! \~english Get all leaf entries (entries without children)
+		//! \~russian Получить все листовые записи (записи без детей)
 		Branch getLeaves();
+
+		//! \~english Get all branch entries (entries with children)
+		//! \~russian Получить все ветвящиеся записи (записи с детьми)
 		Branch getBranches();
+
+		//! \~english Filter branch by filter string
+		//! \~russian Фильтровать ветку по строке фильтра
 		Branch & filter(const PIString & f);
+
+		//! \~english Check if entry with specified name exists
+		//! \~russian Проверить, существует ли запись с указанным именем
 		bool isEntryExists(const PIString & name) const {
 			for (const auto * i: *this)
 				if (entryExists(i, name)) return true;
 			return false;
 		}
+
+		//! \~english Get index of entry in branch
+		//! \~russian Получить индекс записи в ветке
 		int indexOf(const Entry * e) {
 			for (int i = 0; i < size_s(); ++i)
 				if (at(i) == e) return i;
@@ -138,6 +168,8 @@ public:
 	};


+	//! \~english Entry class - represents a single configuration entry
+	//! \~russian Класс Entry - представляет отдельную запись конфигурации
 	class PIP_EXPORT Entry {
 		friend class PIConfig;
 		friend class Branch;
@@ -446,18 +478,24 @@ public:
 	};


-	//! Read configuration from file at path "path" in mode "mode"
+	//! \~english Open configuration from file at path in specified mode
+	//! \~russian Открыть конфигурацию из файла по указанному пути в указанном режиме
 	bool open(const PIString & path, PIIODevice::DeviceMode mode = PIIODevice::ReadWrite);

-	//! Read configuration from string "string" in mode "mode"
+	//! \~english Open configuration from string in specified mode
+	//! \~russian Открыть конфигурацию из строки в указанном режиме
 	bool open(PIString * string, PIIODevice::DeviceMode mode = PIIODevice::ReadWrite);

-	//! Read configuration from custom device "device" in mode "mode"
+	//! \~english Open configuration from custom I/O device in specified mode
+	//! \~russian Открыть конфигурацию из пользовательского устройства ввода-вывода в указанном режиме
 	bool open(PIIODevice * device, PIIODevice::DeviceMode mode = PIIODevice::ReadWrite);

+	//! \~english Check if configuration is opened
+	//! \~russian Проверить, открыта ли конфигурация
 	bool isOpened() const;

-	//! Returns top-level entry with name "vname", if doesn`t exists return entry with value "def" and set *exist to false
+	//! \~english Get top-level entry by name with default value
+	//! \~russian Получить запись верхнего уровня по имени со значением по умолчанию
 	Entry & getValue(const PIString & vname, const PIString & def = PIString(), bool * exists = 0);
 	Entry & getValue(const PIString & vname, const PIString & def = PIString(), bool * exists = 0) const {
 		return const_cast<PIConfig *>(this)->getValue(vname, def, exists);
@@ -504,13 +542,16 @@ public:
 	//! \fn Entry & getValue(const PIString & vname, const double def, bool * exists = 0)
 	//! \brief Returns top-level entry with name "vname" and default value "def"

-
-	//! Returns top-level entries with names with substrings "vname"
+	//! \~english Get all top-level entries with name containing substring
+	//! \~russian Получить все записи верхнего уровня с именем, содержащим подстроку
 	Branch getValues(const PIString & vname);


-	//! Set top-level entry with name "name" value to "value", type to "type" and if "write" immediate write to file. Add new entry if there
-	//! is no suitable exists
+	//! \~english Set value for top-level entry with name
+	//! \~russian Установить значение для записи верхнего уровня с именем
+	//! \details
+	//! \~english Set top-level entry with name "name" value to "value", type to "type" and if "write" immediate write to file.
+	//! Add new entry if there is no suitable exists
 	void setValue(const PIString & name, const PIString & value, const PIString & type = "s", bool write = true);

 	//! Set top-level entry with name "name" value to "value", type to "l" and if "write" immediate write to file. Add new entry if there is
@@ -561,16 +602,20 @@ public:
 	//! no suitable exists
 	void setValue(const PIString & name, const double value, bool write = true) { setValue(name, PIString::fromNumber(value), "f", write); }

-	//! Returns root entry
+	//! \~english Get root entry of configuration tree
+	//! \~russian Получить корневую запись дерева конфигурации
 	Entry & rootEntry() { return root; }

-	//! Returns top-level entries count
+	//! \~english Get count of top-level entries
+	//! \~russian Получить количество записей верхнего уровня
 	int entriesCount() const { return childCount(&root); }

-	//! Returns if top-level entry with name "name" exists
+	//! \~english Check if top-level entry with name exists
+	//! \~russian Проверить, существует ли запись верхнего уровня с указанным именем
 	bool isEntryExists(const PIString & name) const { return entryExists(&root, name); }

-	//! Returns all top-level entries
+	//! \~english Get all top-level entries
+	//! \~russian Получить все записи верхнего уровня
 	Branch allTree() {
 		Branch b;
 		for (auto * i: root._children)
@@ -579,7 +624,8 @@ public:
 		return b;
 	}

-	//! Returns all entries without children
+	//! \~english Get all entries without children (leaves)
+	//! \~russian Получить все записи без детей (листья)
 	Branch allLeaves() {
 		Branch b;
 		allLeaves(b, &root);
@@ -588,35 +634,71 @@ public:
 		return b;
 	}

+	//! \~english Get index of entry by name
+	//! \~russian Получить индекс записи по имени
 	int entryIndex(const PIString & name);

+	//! \~english Get entry name by index
+	//! \~russian Получить имя записи по индексу
 	PIString getName(uint number) { return entryByIndex(number)._name; }
+
+	//! \~english Get entry value by index
+	//! \~russian Получить значение записи по индексу
 	PIString getValueByIndex(uint number) { return entryByIndex(number)._value; }
+
+	//! \~english Get entry type by index
+	//! \~russian Получить тип записи по индексу
 	PIChar getType(uint number) { return entryByIndex(number)._type[0]; }
+
+	//! \~english Get entry comment by index
+	//! \~russian Получить комментарий записи по индексу
 	PIString getComment(uint number) { return entryByIndex(number)._comment; }

+	//! \~english Add new entry with name, value and type
+	//! \~russian Добавить новую запись с именем, значением и типом
 	void addEntry(const PIString & name, const PIString & value, const PIString & type = "s", bool write = true);
+
+	//! \~english Set name of entry by index
+	//! \~russian Установить имя записи по индексу
 	void setName(uint number, const PIString & name, bool write = true);
+
+	//! \~english Set value of entry by index
+	//! \~russian Установить значение записи по индексу
 	void setValue(uint number, const PIString & value, bool write = true);
+
+	//! \~english Set type of entry by index
+	//! \~russian Установить тип записи по индексу
 	void setType(uint number, const PIString & type, bool write = true);
+
+	//! \~english Set comment of entry by index
+	//! \~russian Установить комментарий записи по индексу
 	void setComment(uint number, const PIString & comment, bool write = true);

+	//! \~english Remove entry by name
+	//! \~russian Удалить запись по имени
 	void removeEntry(const PIString & name, bool write = true);
+
+	//! \~english Remove entry by index
+	//! \~russian Удалить запись по индексу
 	void removeEntry(uint number, bool write = true);

 	//! Remove all tree and device content
 	void clear();

-	//! Parse device and build internal tree
+	//! \~english Parse device and build internal tree
+	//! \~russian Прочитать устройство и построить внутреннее дерево
 	void readAll();

-	//! Write all internal tree to device
+	//! \~english Write all internal tree to device
+	//! \~russian Записать всё внутреннее дерево в устройство
 	void writeAll();

-	//! Returns current tree delimiter, default "."
+	//! \~english Get current tree delimiter
+	//! \~russian Получить текущий разделитель дерева
 	const PIString & delimiter() const { return delim; }

-	//! Set current tree delimiter
+	//! \~english Set tree delimiter
+	//! \~russian Установить разделитель дерева
 	void setDelimiter(const PIString & d) {
 		delim = d;
 		setEntryDelim(&root, d);
@@ -708,14 +790,18 @@ inline PICout operator<<(PICout s, const PIConfig::Entry & v) {
 }


-/** \relatesalso PIConfig \relatesalso PIIODevice
- * \brief Service function. useful for configuring devices
- * \details Function takes entry name "name", default value "def" and two
- * \a PIConfig::Entry sections: "em" and their parent "ep". If there is no
- * parent ep = 0. If "ep" is not null and entry "name" exists in "ep" function
- * returns this value. Else returns value of entry "name" in section "em" or
- * "def" if entry doesn`t exists. \n This function useful to read settings
- * from configuration file in implementation \a PIIODevice::configureDevice() function */
+//! \~english Service function for reading device settings from configuration
+//! \~russian Сервисная функция для чтения настроек устройства из конфигурации
+//! \note
+//! \~english Useful for implementing PIIODevice::configureDevice()
+//! \~russian Полезно для реализации PIIODevice::configureDevice()
+//! \~\details Function takes entry name "name", default value "def" and two
+//! \a PIConfig::Entry sections: "em" and their parent "ep". If there is no
+//! parent ep = 0. If "ep" is not null and entry "name" exists in "ep" function
+//! returns this value. Else returns value of entry "name" in section "em" or
+//! "def" if entry doesn`t exists. \n This function useful to read settings
+//! from configuration file in implementation \a PIIODevice::configureDevice() function
+//! \relatesalso PIConfig \relatesalso PIIODevice
 template<typename T>
 T readDeviceSetting(const PIString & name, const T & def, const PIConfig::Entry * em, const PIConfig::Entry * ep) {
 	PIVariant v = PIVariant::fromValue<T>(def);
--- a/libs/main/io_devices/piethernet.h
+++ b/libs/main/io_devices/piethernet.h
@@ -76,30 +76,40 @@ public:


 	//! Set read address
+	//! \~english Set read address
+	//! \~russian Устанавливает адрес для чтения
 	void setReadAddress(const PIString & ip, int port) {
 		addr_r.set(ip, port);
 		setPath(addr_r.toString());
 	}

 	//! Set read address in format "i.i.i.i:p"
+	//! \~english Set read address in format "i.i.i.i:p"
+	//! \~russian Устанавливает адрес для чтения в формате "i.i.i.i:p"
 	void setReadAddress(const PIString & ip_port) {
 		addr_r.set(ip_port);
 		setPath(addr_r.toString());
 	}

 	//! Set read address
+	//! \~english Set read address
+	//! \~russian Устанавливает адрес для чтения
 	void setReadAddress(const PINetworkAddress & addr) {
 		addr_r = addr;
 		setPath(addr_r.toString());
 	}

 	//! Set read IP
+	//! \~english Set read IP
+	//! \~russian Устанавливает IP для чтения
 	void setReadIP(const PIString & ip) {
 		addr_r.setIP(ip);
 		setPath(addr_r.toString());
 	}

 	//! Set read port
+	//! \~english Set read port
+	//! \~russian Устанавливает порт для чтения
 	void setReadPort(int port) {
 		addr_r.setPort(port);
 		setPath(addr_r.toString());
@@ -153,12 +163,16 @@ public:


 	//! Set parameters to "parameters_". You should to reopen %PIEthernet to apply them
+	//! \~english Set parameters to "parameters_". You should to reopen %PIEthernet to apply them
+	//! \~russian Устанавливает параметры "parameters_". Необходимо переоткрыть %PIEthernet для применения
 	void setParameters(PIFlags<PIEthernet::Parameters> parameters_) {
 		params = parameters_;
 		applyParameters();
 	}

 	//! Set parameter "parameter" to state "on". You should to reopen %PIEthernet to apply this
+	//! \~english Set parameter "parameter" to state "on". You should to reopen %PIEthernet to apply this
+	//! \~russian Устанавливает параметр "parameter" в состояние "on". Необходимо переоткрыть %PIEthernet для применения
 	void setParameter(PIEthernet::Parameters parameter, bool on = true) {
 		params.setFlag(parameter, on);
 		applyParameters();
@@ -222,18 +236,24 @@ public:
 	bool connect(bool threaded = true);

 	//! Connect to TCP server with address "ip":"port". Use only for TCP_Client
+	//! \~english Connect to TCP server with address "ip":"port". Use only for TCP_Client
+	//! \~russian Подключается к TCP серверу по адресу "ip":"port". Только для TCP_Client
 	bool connect(const PIString & ip, int port, bool threaded = true) {
 		setPath(ip + PIStringAscii(":") + PIString::fromNumber(port));
 		return connect(threaded);
 	}

 	//! Connect to TCP server with address "ip_port". Use only for TCP_Client
+	//! \~english Connect to TCP server with address "ip_port". Use only for TCP_Client
+	//! \~russian Подключается к TCP серверу по адресу "ip_port". Только для TCP_Client
 	bool connect(const PIString & ip_port, bool threaded = true) {
 		setPath(ip_port);
 		return connect(threaded);
 	}

 	//! Connect to TCP server with address "addr". Use only for TCP_Client
+	//! \~english Connect to TCP server with address "addr". Use only for TCP_Client
+	//! \~russian Подключается к TCP серверу по адресу "addr". Только для TCP_Client
 	bool connect(const PINetworkAddress & addr, bool threaded = true) {
 		setPath(addr.toString());
 		return connect(threaded);
@@ -269,11 +289,15 @@ public:
 	bool send(const void * data, int size, bool threaded = false);

 	//! Send data "data" with size "size" to address "ip":"port"
+	//! \~english Send data "data" with size "size" to address "ip":"port"
+	//! \~russian Отправляет данные "data" размером "size" на адрес "ip":"port"
 	bool send(const PIString & ip, int port, const void * data, int size, bool threaded = false) {
 		return send(PINetworkAddress(ip, port), data, size, threaded);
 	}

 	//! Send data "data" with size "size" to address "ip_port"
+	//! \~english Send data "data" with size "size" to address "ip_port"
+	//! \~russian Отправляет данные "data" размером "size" на адрес "ip_port"
 	bool send(const PIString & ip_port, const void * data, int size, bool threaded = false) {
 		return send(PINetworkAddress(ip_port), data, size, threaded);
 	}
@@ -285,11 +309,15 @@ public:
 	bool send(const PIByteArray & data, bool threaded = false);

 	//! Send data "data" to address "ip":"port" for UDP
+	//! \~english Send data "data" to address "ip":"port" for UDP
+	//! \~russian Отправляет данные "data" на адрес "ip":"port" для UDP
 	bool send(const PIString & ip, int port, const PIByteArray & data, bool threaded = false) {
 		return send(PINetworkAddress(ip, port), data, threaded);
 	}

 	//! Send data "data" to address "ip_port" for UDP
+	//! \~english Send data "data" to address "ip_port" for UDP
+	//! \~russian Отправляет данные "data" на адрес "ip_port" для UDP
 	bool send(const PIString & ip_port, const PIByteArray & data, bool threaded = false) {
 		return send(PINetworkAddress(ip_port), data, threaded);
 	}
--- a/libs/main/io_devices/piiodevice.h
+++ b/libs/main/io_devices/piiodevice.h
@@ -56,26 +56,20 @@ typedef std::function<bool(const uchar *, int, void *)> ReadRetFunc;

 #else

-#  define REGISTER_DEVICE(name)                                                                                    \
-	  STATIC_INITIALIZER_BEGIN                                                                                     \
-		  PIIODevice::registerDevice(name::fullPathPrefixS(), #name, []() -> PIIODevice * { return new name(); }); \
-	  STATIC_INITIALIZER_END
+#  define REGISTER_DEVICE(name)                                                                                \
+	STATIC_INITIALIZER_BEGIN                                                                                   \
+	  PIIODevice::registerDevice(name::fullPathPrefixS(), #name, []() -> PIIODevice * { return new name(); }); \
+	STATIC_INITIALIZER_END

-#  define PIIODEVICE(name, prefix)                   \
-	  PIOBJECT_SUBCLASS(name, PIIODevice)            \
-	  PIIODevice * copy() const override {           \
-		  return new name();                         \
-	  }                                              \
-                                                     \
-  public:                                            \
-	  PIConstChars fullPathPrefix() const override { \
-		  return prefix;                             \
-	  }                                              \
-	  static PIConstChars fullPathPrefixS() {        \
-		  return prefix;                             \
-	  }                                              \
-                                                     \
-  private:
+#  define PIIODEVICE(name, prefix)                                  \
+	PIOBJECT_SUBCLASS(name, PIIODevice)                             \
+	PIIODevice * copy() const override { return new name(); }       \
+                                                                    \
+public:                                                             \
+	PIConstChars fullPathPrefix() const override { return prefix; } \
+	static PIConstChars fullPathPrefixS() { return prefix; }        \
+                                                                    \
+private:


 #endif
--- a/libs/main/io_devices/piiostream.h
+++ b/libs/main/io_devices/piiostream.h
@@ -49,11 +49,15 @@ public:
 		resetReadError();
 	}

+	//! \~english Append data to stream
+	//! \~russian Добавляет данные в поток
 	bool binaryStreamAppendImp(const void * d, size_t s) {
 		if (!dev) return false;
 		return (dev->write(d, s) == (int)s);
 	}

+	//! \~english Take data from stream
+	//! \~russian Извлекает данные из потока
 	bool binaryStreamTakeImp(void * d, size_t s) {
 		if (!dev) return false;
 		return (dev->read(d, s) == (int)s);
@@ -90,6 +94,8 @@ public:
 		if (io_string) delete io_string;
 	}

+	//! \~english Assign "device" device
+	//! \~russian Назначает устройство "device"
 	void setDevice(PIIODevice * device) {
 		bin_stream = PIIOBinaryStream(device);
 		setStream(&bin_stream);
--- a/libs/main/io_devices/piserial.h
+++ b/libs/main/io_devices/piserial.h
@@ -216,6 +216,8 @@ public:
 	//! \~russian Переключает состояние передачи в break
 	bool setBreak(bool enabled);

+	//! \~english Set VTime parameter
+	//! \~russian Устанавливает параметр VTime
 	void setVTime(int t) {
 		vtime = t;
 		applySettings();