merged AI doc, some new pages

libs/main/serialization/pichunkstream.h

@@ -29,52 +29,74 @@
 #include "pibytearray.h"
 
 
-//! \ingroup Serialization
+//! \~\ingroup Serialization
 //! \~\brief
 //! \~english Class for binary de/serialization.
 //! \~russian Класс для бинарной де/сериализации.
+//! \~\details
+//! \~english PIChunkStream provides a binary markup serialization stream that allows reading and writing structured data chunks with IDs.
+//! \~russian PIChunkStream обеспечивает бинарный поток с разметкой для чтения и записи структурированных данных-чанков с ID.
 class PIP_EXPORT PIChunkStream {
 public:
-	//! \~english
-	//! Version of data packing. Read-access %PIChunkStream automatic detect version, but write-access
-	//! %PIChunkStream by default write in new version, be careful!
-	//! \~russian
-	//! Версия хранения данных. %PIChunkStream на чтение автоматически определяет версию, но для записи
-	//! использует по умолчанию новую, осторожно!
+	//! \~english Version of data packing.
+	//! \~russian Версия хранения данных.
+	//! \~\details
+	//! \~english Read-access %PIChunkStream automatic detect version, but write-access %PIChunkStream by default write in new version, be
+	//! careful!
+	//! \~russian %PIChunkStream на чтение автоматически определяет версию, но для записи использует по умолчанию новую, осторожно!
 	enum Version {
 		Version_1 /*! \~english First, old version \~russian Первая, старая версия */,
 		Version_2 /*! \~english Second, more optimized version \~russian Вторая, более оптимизированная версия */ = 2,
 	};
 
-	//! \~english Contructs stream for read from "data"
+	//! \~english Constructs stream for read from "data"
 	//! \~russian Создает поток на чтение из "data"
 	PIChunkStream(const PIByteArray & data): version_(Version_2) { setSource(data); }
 
-	//! \~english Contructs stream for read or write to/from "data", or empty stream for write if "data" = 0
+	//! \~english Constructs stream for read or write to/from "data", or empty stream for write if "data" = 0
 	//! \~russian Создает поток на чтение или запись из/в "data", или пустой поток на запись если "data" = 0
 	PIChunkStream(PIByteArray * data = 0, Version v = Version_2): version_(v) { setSource(data); }
 
-	//! \~english Contructs empty stream for write with version \"v\"
+	//! \~english Constructs empty stream for write with version \"v\"
 	//! \~russian Создает пустой поток на запись с версией \"v\"
 	PIChunkStream(Version v): version_(v) { setSource(0); }
 
+	//! \~english Destructor
+	//! \~russian Деструктор
 	~PIChunkStream();
 
+	//! \~english Nested template struct for chunk data
+	//! \~russian Вложенный шаблонный структура для данных чанка
 	template<typename T>
 	struct Chunk {
+		//! \~english Constructor with ID and data
+		//! \~russian Конструктор с ID и данными
 		Chunk(int i, const T & d): id(i), data(d) {}
+		//! \~english Chunk ID
+		//! \~russian ID чанка
 		int id;
+		//! \~english Chunk data
+		//! \~russian Данные чанка
 		T data;
 	};
+	//! \~english Nested template struct for constant chunk data
+	//! \~russian Вложенный шаблонный структура для константных данных чанка
 	template<typename T>
 	struct ChunkConst {
+		//! \~english Constructor with ID and data
+		//! \~russian Конструктор с ID и данными
 		ChunkConst(int i, const T & d): id(i), data(d) {}
+		//! \~english Chunk ID
+		//! \~russian ID чанка
 		int id;
+		//! \~english Constant chunk data reference
+		//! \~russian Константная ссылка на данные чанка
 		const T & data;
 	};
 
 	//! \~english Returns chunk with ID "id" and value "data" for write to stream
 	//! \~russian Возвращает чанк с ID "id" и значением "data" для записи в поток
+	//! \~\sa chunk()
 	template<typename T>
 	static ChunkConst<T> chunk(int id, const T & data) {
 		return ChunkConst<T>(id, data);
@@ -82,6 +104,7 @@ public:
 
 	//! \~english Add to this stream chunk with ID "id" and value "data"
 	//! \~russian Добавляет в этот поток чанк с ID "id" и значением "data"
+	//! \~\sa chunk()
 	template<typename T>
 	PIChunkStream & add(int id, const T & data) {
 		*this << ChunkConst<T>(id, data);
@@ -96,6 +119,9 @@ public:
 	//! Извлекает %PIByteArray из "stream" и инициализирует им поток.
 	//! Если указан "read_all", то вызывает \a readAll() после инициализации.
 	//! Возвращает если ли данные для чтения.
+	//! \~\note
+	//! \~english You should call \a readAll() before using \a getData() or \a get() methods
+	//! \~russian Перед использованием методов \a getData() или \a get() следует вызвать \a readAll()
 	template<typename T>
 	bool extract(PIBinaryStream<T> & stream, bool read_all = false) {
 		stream >> tmp_data;
@@ -106,7 +132,12 @@ public:
 		return true;
 	}
 
+	//! \~english Sets source buffer for read from "data"
+	//! \~russian Устанавливает исходный буфер для чтения из "data"
 	void setSource(const PIByteArray & data);
+
+	//! \~english Sets source buffer for read or write to/from "data", or empty stream for write if "data" = 0
+	//! \~russian Устанавливает исходный буфер для чтения или записи из/в "data", или пустой поток на запись если "data" = 0
 	void setSource(PIByteArray * data);
 
 	//! \~english Returns internal buffer with written data
@@ -122,20 +153,32 @@ public:
 	Version version() const { return (Version)version_; }
 
 
-	//! \~english  Read one chunk from stream and returns its ID
+	//! \~english Reads one chunk from stream and returns its ID
 	//! \~russian Читает один чанк из потока и возвращает его ID
+	//! \~\details
+	//! \~english Reads the next chunk from the stream and stores its ID for subsequent \a getData() or \a get() calls
+	//! \~russian Читает следующий чанк из потока и сохраняет его ID для последующих вызовов \a getData() или \a get()
 	int read();
 
 	//! \~english Read all chunks from stream. This function just index input data
 	//! \~russian Читает все чанки из потока. Данный метод лишь индексирует данные
+	//! \~\details
+	//! \~english This function indexes input data to allow random access via \a getData(int id) and \a get(int id, T & v)
+	//! \~russian Эта функция индексирует входные данные для возможности случайного доступа через \a getData(int id) и \a get(int id, T & v)
 	void readAll();
 
-	//! \~english Returns last readed chunk ID
+	//! \~english Returns last read chunk ID
 	//! \~russian Возвращает ID последнего прочитанного чанка
+	//! \~\details
+	//! \~english Returns the ID of the last chunk read by \a read() method
+	//! \~russian Возвращает ID последнего чанка, прочитанного методом \a read()
 	int getID() { return last_id; }
 
-	//! \~english Returns value of last readed chunk
+	//! \~english Returns value of last read chunk
 	//! \~russian Возвращает значение последнего прочитанного чанка
+	//! \~\note
+	//! \~english Call \a read() first to read a chunk before using this method
+	//! \~russian Сначала вызовите \a read() для чтения чанка перед использованием этого метода
 	template<typename T>
 	T getData() const {
 		T ret{};
@@ -144,8 +187,11 @@ public:
 		return ret;
 	}
 
-	//! \~english Returns value of chunk with ID \"id\". You should call \a readAll() before using this function!
-	//! \~russian Возвращает значение чанка с ID \"id\". Необходимо вызвать \a readAll() перед использованием этого метода!
+	//! \~english Returns value of chunk with ID \"id\"
+	//! \~russian Возвращает значение чанка с ID \"id\"
+	//! \~\note
+	//! \~english You should call \a readAll() before using this function!
+	//! \~russian Необходимо вызвать \a readAll() перед использованием этого метода!
 	template<typename T>
 	T getData(int id) const {
 		T ret{};
@@ -156,15 +202,21 @@ public:
 		return ret;
 	}
 
-	//! \~english Place value of last readed chunk into \"v\"
+	//! \~english Places value of last read chunk into \"v\"
 	//! \~russian Записывает значение последнего прочитанного чанка в \"v\"
+	//! \~\note
+	//! \~english Call \a read() first to read a chunk before using this method
+	//! \~russian Сначала вызовите \a read() для чтения чанка перед использованием этого метода
 	template<typename T>
 	void get(T & v) const {
 		v = getData<T>();
 	}
 
-	//! \~english Place value of chunk with ID \"id\" into \"v\". You should call \a readAll() before using this function!
-	//! \~russian Записывает значение чанка с ID \"id\" в \"v\". Необходимо вызвать \a readAll() перед использованием этого метода!
+	//! \~english Places value of chunk with ID \"id\" into \"v\"
+	//! \~russian Записывает значение чанка с ID \"id\" в \"v\"
+	//! \~\note
+	//! \~english You should call \a readAll() before using this function!
+	//! \~russian Необходимо вызвать \a readAll() перед использованием этого метода!
 	template<typename T>
 	const PIChunkStream & get(int id, T & v) const {
 		CacheEntry pos = data_map.value(id);
@@ -174,8 +226,11 @@ public:
 		return *this;
 	}
 
-	//! \~english Replace value of chunk with ID \"id\" to \"v\". You should call \a readAll() before using this function!
-	//! \~russian Заменяет значение чанка с ID \"id\" на \"v\". Необходимо вызвать \a readAll() перед использованием этого метода!
+	//! \~english Replaces value of chunk with ID \"id\" to \"v\"
+	//! \~russian Заменяет значение чанка с ID \"id\" на \"v\"
+	//! \~\note
+	//! \~english You should call \a readAll() before using this function!
+	//! \~russian Необходимо вызвать \a readAll() перед использованием этого метода!
 	template<typename T>
 	PIChunkStream & set(int id, const T & v) {
 		PIByteArray ba;
@@ -211,6 +266,8 @@ private:
 	friend PIChunkStream & operator<<(PIChunkStream & s, const PIChunkStream::ChunkConst<T> & c);
 };
 
+//! \~english Stream output operator for Chunk
+//! \~russian Оператор вывода в поток для Chunk
 template<typename T>
 PIChunkStream & operator<<(PIChunkStream & s, const PIChunkStream::Chunk<T> & c) {
 	PIByteArray ba;
@@ -227,6 +284,9 @@ PIChunkStream & operator<<(PIChunkStream & s, const PIChunkStream::Chunk<T> & c)
 	}
 	return s;
 }
+
+//! \~english Stream output operator for ChunkConst
+//! \~russian Оператор вывода в поток для ChunkConst
 template<typename T>
 PIChunkStream & operator<<(PIChunkStream & s, const PIChunkStream::ChunkConst<T> & c) {
 	PIByteArray ba;