merged AI doc, some new pages

libs/main/math/picrc.h

@@ -1,9 +1,8 @@
-/*! \file picrc.h
- * \ingroup Math
- * \~\brief
- * \~english CRC checksum calculation
- * \~russian Вычисление CRC контрольной суммы
- */
+//! \~\file picrc.h
+//! \~\ingroup Math
+//! \~\brief
+//! \~english CRC checksum calculation
+//! \~russian Вычисление CRC контрольной суммы
 /*
     PIP - Platform Independent Primitives
     CRC checksum calculator
@@ -28,13 +27,21 @@
 
 #include "pistring.h"
 
+//! \~\ingroup Math
+//! \~\brief
+//! \~english Fixed-width unsigned helper used by generic CRC implementations.
+//! \~russian Вспомогательный беззнаковый тип фиксированной ширины для обобщенных реализаций CRC.
 template<int L>
 class PIP_EXPORT uint_cl {
 public:
+	//! \~english Constructs a zero-filled value.
+	//! \~russian Создает значение, заполненное нулями.
 	uint_cl() {
 		for (int i = 0; i < L / 8; ++i)
 			data_[i] = 0;
 	}
+	//! \~english Constructs a copy.
+	//! \~russian Создает копию.
 	uint_cl(const uint_cl<L> & v) {
 		for (int i = 0; i < L / 8; ++i)
 			data_[i] = v.data_[i];
@@ -96,6 +103,8 @@ public:
 			data_[i] = 0;
 	}
 
+	//! \~english Returns \c true when at least one bit is set.
+	//! \~russian Возвращает \c true, если установлен хотя бы один бит.
 	operator bool() {
 		for (int i = 0; i < L / 8; ++i)
 			if (data_[i] > 0) return true;
@@ -152,6 +161,8 @@ public:
 		return t;
 	}
 
+	//! \~english Adds two fixed-width values with carry propagation.
+	//! \~russian Складывает два значения фиксированной ширины с переносом.
 	uint_cl<L> operator+(const uint_cl<L> & v) {
 		uint_cl<L> t;
 		uint cv;
@@ -165,6 +176,8 @@ public:
 		return t;
 	}
 
+	//! \~english Returns bitwise AND with another value.
+	//! \~russian Возвращает побитовое И с другим значением.
 	uint_cl<L> operator&(const uint_cl<L> & v) const {
 		uint_cl<L> t;
 		for (int i = 0; i < L / 8; ++i)
@@ -182,6 +195,8 @@ public:
 	uint_cl<L> operator&(const long & v) const { return *this & uint_cl<L>(v); }
 	uint_cl<L> operator&(const llong & v) const { return *this & uint_cl<L>(v); }
 
+	//! \~english Returns bitwise OR with another value.
+	//! \~russian Возвращает побитовое ИЛИ с другим значением.
 	uint_cl<L> operator|(const uint_cl<L> & v) const {
 		uint_cl<L> t;
 		for (int i = 0; i < L / 8; ++i)
@@ -199,6 +214,8 @@ public:
 	uint_cl<L> operator|(const long & v) const { return *this | uint_cl<L>(v); }
 	uint_cl<L> operator|(const llong & v) const { return *this | uint_cl<L>(v); }
 
+	//! \~english Returns bitwise XOR with another value.
+	//! \~russian Возвращает побитовое исключающее ИЛИ с другим значением.
 	uint_cl<L> operator^(const uint_cl<L> & v) const {
 		uint_cl<L> t;
 		for (int i = 0; i < L / 8; ++i)
@@ -216,6 +233,8 @@ public:
 	uint_cl<L> operator^(const long & v) const { return *this ^ uint_cl<L>(v); }
 	uint_cl<L> operator^(const llong & v) const { return *this ^ uint_cl<L>(v); }
 
+	//! \~english Less than operator
+	//! \~russian Оператор меньше
 	bool operator<(const uint_cl<L> & v) const {
 		for (int i = 0; i < L / 8; ++i) {
 			if (v.data_[i] > data_[i]) return true;
@@ -223,6 +242,9 @@ public:
 		}
 		return false;
 	}
+
+	//! \~english Less than or equal operator
+	//! \~russian Оператор меньше или равно
 	bool operator<=(const uint_cl<L> & v) const {
 		for (int i = 0; i < L / 8; ++i) {
 			if (v.data_[i] > data_[i]) return true;
@@ -230,6 +252,9 @@ public:
 		}
 		return true;
 	}
+
+	//! \~english Greater than operator
+	//! \~russian Оператор больше
 	bool operator>(const uint_cl<L> & v) const {
 		for (int i = 0; i < L / 8; ++i) {
 			if (v.data_[i] < data_[i]) return true;
@@ -237,6 +262,9 @@ public:
 		}
 		return false;
 	}
+
+	//! \~english Greater than or equal operator
+	//! \~russian Оператор больше или равно
 	bool operator>=(const uint_cl<L> & v) const {
 		for (int i = 0; i < L / 8; ++i) {
 			if (v.data_[i] < data_[i]) return true;
@@ -244,18 +272,29 @@ public:
 		}
 		return true;
 	}
+
+	//! \~english Equality operator
+	//! \~russian Оператор равенства
 	bool operator==(const uint_cl<L> & v) const {
 		for (int i = 0; i < L / 8; ++i)
 			if (v.data_[i] != data_[i]) return false;
 		return true;
 	}
+
+	//! \~english Inequality operator
+	//! \~russian Оператор неравенства
 	bool operator!=(const uint_cl<L> & v) const {
 		for (int i = 0; i < L / 8; ++i)
 			if (v.data_[i] != data_[i]) return true;
 		return false;
 	}
+
+	//! \~english Less than or equal operator (specialized for 8-bit)
+	//! \~russian Оператор меньше или равно (специализация для 8 бит)
 	bool operator<=(const uint_cl<8> & v1) { return (*(uchar *)data()) <= (*(uchar *)v1.data()); }
 
+	//! \~english Returns a value shifted right by the specified bit count.
+	//! \~russian Возвращает значение, сдвинутое вправо на указанное число битов.
 	uint_cl<L> operator>>(const int & c) const {
 		uint_cl<L> t;
 		int l = L - c;
@@ -271,6 +310,8 @@ public:
 		return t;
 	}
 	uint_cl<L> operator>>(const uint & c) const { return (*this << (int)c); }
+	//! \~english Returns a value shifted left by the specified bit count.
+	//! \~russian Возвращает значение, сдвинутое влево на указанное число битов.
 	uint_cl<L> operator<<(const int & c) const {
 		uint_cl<L> t;
 		int l = L - c;
@@ -287,17 +328,23 @@ public:
 	}
 	uint_cl<L> operator<<(const uint & c) const { return (*this >> (int)c); }
 
+	//! \~english Inverts all bits in place.
+	//! \~russian Инвертирует все биты на месте.
 	uint_cl<L> & inverse() const {
 		for (int i = 0; i < L / 8; ++i)
 			data_[i] = ~data_[i];
 		return *this;
 	}
+	//! \~english Returns a copy with all bits inverted.
+	//! \~russian Возвращает копию с инвертированными битами.
 	uint_cl<L> inversed() const {
 		uint_cl<L> t(*this);
 		for (int i = 0; i < L / 8; ++i)
 			t.data_[i] = ~t.data_[i];
 		return t;
 	}
+	//! \~english Returns a copy with bit order reversed.
+	//! \~russian Возвращает копию с обратным порядком битов.
 	uint_cl<L> reversed() const {
 		uint_cl<L> t;
 		bool bit;
@@ -311,8 +358,14 @@ public:
 		return t;
 	}
 
+	//! \~english Returns raw byte storage.
+	//! \~russian Возвращает сырое байтовое представление.
 	const uchar * data() const { return data_; }
+	//! \~english Returns raw byte storage.
+	//! \~russian Возвращает сырое байтовое представление.
 	uchar * data() { return data_; }
+	//! \~english Returns storage length in bytes.
+	//! \~russian Возвращает длину хранения в байтах.
 	uint length() const { return L / 8; }
 
 private:
@@ -320,6 +373,8 @@ private:
 };
 
 
+//! \~english Returns a byte with reversed bit order.
+//! \~russian Возвращает байт с обратным порядком битов.
 inline uchar reverseByte(uchar b) {
 	uchar ret = 0;
 	bool bit;
@@ -330,9 +385,15 @@ inline uchar reverseByte(uchar b) {
 	return ret;
 }
 
+//! \~\ingroup Math
+//! \~\brief
+//! \~english Generic table-driven CRC calculator for a polynomial width \a L.
+//! \~russian Универсальный табличный калькулятор CRC для полинома ширины \a L.
 template<uint L, typename N = uint_cl<L>>
 class PIP_EXPORT PICRC {
 public:
+	//! \~english Constructs a calculator with the specified polynomial and default CRC conventions.
+	//! \~russian Создает калькулятор с указанным полиномом и стандартными настройками CRC.
 	PICRC(const N & poly = N()) {
 		poly_              = poly;
 		reverse_poly       = true;
@@ -341,6 +402,9 @@ public:
 		reverse_before_xor = reverse_data = false;
 		initTable();
 	}
+
+	//! \~english Constructs a calculator with fully specified initialization parameters.
+	//! \~russian Создает калькулятор с полностью заданными параметрами инициализации.
 	PICRC(const N & poly, bool reverse_poly_, const N & initial, const N & out_xor) {
 		poly_              = poly;
 		reverse_poly       = reverse_poly_;
@@ -350,15 +414,33 @@ public:
 		initTable();
 	}
 
+
+	//! \~english Sets the initial CRC value.
+	//! \~russian Устанавливает начальное значение CRC.
 	void setInitial(const N & v) { init_ = v; }
+
+	//! \~english Sets the final XOR value.
+	//! \~russian Устанавливает финальное значение XOR.
 	void setOutXor(const N & v) { out_ = v; }
+
+	//! \~english Enables or disables polynomial bit reversal and rebuilds the lookup table.
+	//! \~russian Включает или отключает реверс полинома и перестраивает таблицу поиска.
 	void setReversePolynome(bool yes) {
 		reverse_poly = yes;
 		initTable();
 	}
+
+	//! \~english Reverses the resulting CRC before applying the output XOR.
+	//! \~russian Разворачивает итоговый CRC перед применением выходного XOR.
 	void setReverseOutBeforeXOR(bool yes) { reverse_before_xor = yes; }
+
+	//! \~english Reverses bits in each input byte before processing.
+	//! \~russian Разворачивает биты в каждом входном байте перед обработкой.
 	void setReverseDataBytes(bool yes) { reverse_data = yes; }
 
+
+	//! \~english Rebuilds the 256-entry lookup table for the current polynomial settings.
+	//! \~russian Перестраивает таблицу из 256 элементов для текущих настроек полинома.
 	void initTable() {
 		N tmp, pol = reverse_poly ? reversed(poly_) : poly_;
 		// cout << std::hex << "poly " << (uint)N(poly_) << " -> " << (uint)N(pol) << endl;
@@ -370,6 +452,9 @@ public:
 		}
 	}
 
+
+	//! \~english Calculates CRC for a raw memory block.
+	//! \~russian Вычисляет CRC для блока памяти.
 	N calculate(const void * data, int size) {
 		N crc        = init_;
 		uchar *data_ = (uchar *)data, cb;
@@ -385,7 +470,13 @@ public:
 		if (reverse_before_xor) crc = reversed(crc);
 		return crc ^ out_;
 	}
+
+	//! \~english Calculates CRC for a byte array.
+	//! \~russian Вычисляет CRC для массива байтов.
 	N calculate(const PIByteArray & d) { return calculate(d.data(), d.size()); }
+
+	//! \~english Calculates CRC for a null-terminated string.
+	//! \~russian Вычисляет CRC для нуль-терминированной строки.
 	N calculate(const char * str) {
 		PIByteArray s(PIString(str).toByteArray());
 		return calculate(s.data(), s.size_s());
@@ -425,20 +516,43 @@ inline uint PICRC<32, uint>::inversed(const uint & v) {
 	return ~v;
 }
 
+//! \~english CRC-32 calculator type.
+//! \~russian Тип калькулятора CRC-32.
 typedef PICRC<32, uint> CRC_32;
+
+//! \~english CRC-24 calculator type.
+//! \~russian Тип калькулятора CRC-24.
 typedef PICRC<24> CRC_24;
+
+//! \~english CRC-16 calculator type.
+//! \~russian Тип калькулятора CRC-16.
 typedef PICRC<16, ushort> CRC_16;
+
+//! \~english CRC-8 calculator type.
+//! \~russian Тип калькулятора CRC-8.
 typedef PICRC<8, uchar> CRC_8;
 
+
+//! \~english Create standard CRC-32 calculator
+//! \~russian Создать стандартный калькулятор CRC-32
 inline CRC_32 standardCRC_32() {
 	return CRC_32(0x04C11DB7, true, 0xFFFFFFFF, 0xFFFFFFFF);
 }
+
+//! \~english Create standard CRC-16 calculator
+//! \~russian Создать стандартный калькулятор CRC-16
 inline CRC_16 standardCRC_16() {
 	return CRC_16(0x8005, true, 0x0, 0x0);
 }
+
+//! \~english Create standard CRC-16 Modbus calculator
+//! \~russian Создать стандартный калькулятор CRC-16 Modbus
 inline CRC_16 standardCRC_16_Modbus() {
 	return CRC_16(0x8005, 0xFFFF, 0xFFFF, false);
 }
+
+//! \~english Create standard CRC-8 calculator
+//! \~russian Создать стандартный калькулятор CRC-8
 inline CRC_8 standardCRC_8() {
 	return CRC_8(0xD5, true, 0x0, 0x0);
 }