merged AI doc, some new pages

libs/main/thread/piprotectedvariable.h

@@ -1,13 +1,12 @@
-/*! \file piprotectedvariable.h
- * \ingroup Thread
- * \~\brief
- * \~english Thread-safe variable
- * \~russian Потокобезопасная переменная
- */
+//! \~\file piprotectedvariable.h
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Thread-safe variable
+//! \~russian Потокобезопасная переменная
 /*
 	PIP - Platform Independent Primitives
 	Thread-safe variable
-	Ivan Pelipenko peri4ko@yandex.ru, Stephan Fomenko, Andrey Bychkov work.a.b@yandex.ru
+	Ivan Pelipenko peri4ko@yandex.ru
 
 	This program is free software: you can redistribute it and/or modify
 	it under the terms of the GNU Lesser General Public License as published by
@@ -28,22 +27,36 @@
 
 #include "pimutex.h"
 
-
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Thread-safe variable template class
+//! \~russian Шаблонный класс потокобезопасной переменной
 template<typename T>
 class PIP_EXPORT PIProtectedVariable {
 public:
-	//! \~english
-	//! \~russian
+	//! \~\brief
+	//! \~english Pointer-like wrapper returned by \a getRef() while the protected value remains locked.
+	//! \~russian Указателеподобная обертка, возвращаемая \a getRef(), пока защищенное значение остается заблокированным.
 	class PIP_EXPORT Pointer {
 		friend class PIProtectedVariable<T>;
 
 	public:
+		//! \~english Copies wrapper state for access to the same protected value.
+		//! \~russian Копирует состояние обертки для доступа к тому же защищенному значению.
 		Pointer(const Pointer & v): pv(v.pv), counter(v.counter + 1) {}
+
+		//! \~english Destroys wrapper and releases the mutex when it owns the original lock.
+		//! \~russian Уничтожает обертку и освобождает мьютекс, когда она владеет исходной блокировкой.
 		~Pointer() {
 			if (counter == 0) pv.mutex.unlock();
 		}
 
+		//! \~english Returns pointer access to the protected value.
+		//! \~russian Возвращает указательный доступ к защищенному значению.
 		T * operator->() { return &pv.var; }
+
+		//! \~english Returns reference access to the protected value.
+		//! \~russian Возвращает ссылочный доступ к защищенному значению.
 		T & operator*() { return pv.var; }
 
 	private:
@@ -54,29 +67,29 @@ public:
 		int counter = 0;
 	};
 
-	//! \~english Sets value to \"v\"
-	//! \~russian Устанавливает значение как \"v\"
+	//! \~english Replaces the protected value with \a v.
+	//! \~russian Заменяет защищенное значение на \a v.
 	void set(T v) {
 		PIMutexLocker _ml(mutex);
 		var = std::move(v);
 	}
 
-	//! \~english Lock mutex and returns reference wrapper of value. Unlock on variable destructor.
-	//! \~russian Блокирует мьютекс и возвращает класс-обертку на значение. Разблокирует в деструкторе переменной.
+	//! \~english Locks the value and returns wrapper-based access to it.
+	//! \~russian Блокирует значение и возвращает обертку для доступа к нему.
 	Pointer getRef() {
 		mutex.lock();
 		return Pointer(*this);
 	}
 
-	//! \~english Returns copy of value
-	//! \~russian Возвращает копию значения
+	//! \~english Returns a copy of the protected value.
+	//! \~russian Возвращает копию защищенного значения.
 	T get() const {
 		PIMutexLocker _ml(mutex);
 		return var;
 	}
 
-	//! \~english Sets value to \"v\"
-	//! \~russian Устанавливает значение как \"v\"
+	//! \~english Replaces the protected value with \a v.
+	//! \~russian Заменяет защищенное значение на \a v.
 	PIProtectedVariable<T> & operator=(T v) {
 		set(std::move(v));
 		return *this;
@@ -89,4 +102,4 @@ private:
 };
 
 
-#endif
+#endif // PIPROTECTEDVARIABLE_H