merged AI doc, some new pages

doc/pages/iostream.md

@@ -3,8 +3,10 @@
 
 \~english
 
+\a PIBinaryStream is the binary serialization interface. For versioned, extensible formats with chunk ids see \ref chunk_stream. It is not used standalone; only as a mixin or via concrete classes such as \a PIByteArray and \a PIIOBinaryStream. Use it to save or load any data. Trivial types are read/written as memory blocks unless custom operators are defined; non-trivial types must have stream operators or the code will not compile. Containers are supported under the same rules. Enums are treated as int, bool as one byte. Write operators append to the stream; read operators consume from the beginning. Macros: \c BINARY_STREAM_FRIEND(T), \c BINARY_STREAM_WRITE(T), \c BINARY_STREAM_READ(T) (inside them \c s is the stream, \c v is the value).
+
 \~russian
-%PIBinaryStream представляет собой интерфейс бинарной сериализации.
+%PIBinaryStream представляет собой интерфейс бинарной сериализации. Для версионных расширяемых форматов с id чанков см. \ref chunk_stream.
 Не может быть использован в чистом виде, только в виде миксина или
 готовых классов: PIByteArray и PIIOBinaryStream.
 
@@ -28,7 +30,7 @@
  * BINARY_STREAM_READ(T) - чтение из потока, "s" - объект потока, "v" - объект типа T.
  
 Пример:
-\~\code{.cpp}
+\code{.cpp}
 #include <pibytearray.h>
 
 class MyType {
@@ -69,7 +71,7 @@ int main(int argc, char * argv[]) {
 
 \~english Result:
 \~russian Результат:
-\~\code{.cpp}
+\code{.cpp}
 0a000000040000007400650078007400
 10 text
 
@@ -84,7 +86,7 @@ operators of this class simply store/restore data block to/from stream:
 Для сохранения/извлечения блоков произвольных данных используется класс PIMemoryBlock.
 Потоковые операторы для него просто сохраняют/извлекают блоки байтов в/из потока:
 
-\~\code{.cpp}
+\code{.cpp}
 float a_read[10], a_write[10];
 for (int i = 0; i < 10; ++i) {
 	a_read [i] = 0.f;
@@ -103,7 +105,7 @@ for (int i = 0; i < 10; ++i)
 
 \~english Result:
 \~russian Результат:
-\~\code{.cpp}
+\code{.cpp}
 00000000cdcccc3dcdcc4c3e9a99993ecdcccc3e0000003f9a99193f3333333fcdcc4c3f6666663f
 0
 0.1
@@ -119,7 +121,9 @@ for (int i = 0; i < 10; ++i)
 
 \~english
 
+If a read runs out of data (e.g. end of array or file), the stream's \c wasReadError() returns \c true. Check it after reads to handle errors correctly.
+
 \~russian
 Если при чтении из потока не хватило данных (например, закончился массив или файл), то проверка
-объекта потока на wasReadError() вернёт true. Рекомендуется делать эту проверку после чтения
+объекта потока на \c wasReadError() вернёт \c true. Рекомендуется делать эту проверку после чтения
 данных для корректной обработки ошибки.