merged AI doc, some new pages

libs/main/thread/pisemaphore.h

@@ -1,13 +1,13 @@
 /*! \file pisemaphore.h
- * \ingroup Semaphore
+ * \ingroup Thread
  * \~\brief
- * \~english Basic semaphore
- * \~russian Простой семафор
+ * \~english Counting semaphore for shared resources
+ * \~russian Счетный семафор для общих ресурсов
  */
 /*
     PIP - Platform Independent Primitives
-	PISemaphore, PISemaphoreLocker
-	Ivan Pelipenko peri4ko@yandex.ru
+    PISemaphore, PISemaphoreLocker
+    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,7 +28,10 @@
 
 #include "piconditionvar.h"
 
-
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Counting semaphore that tracks available resource units.
+//! \~russian Счетный семафор, отслеживающий количество доступных единиц ресурса.
 class PIP_EXPORT PISemaphore {
 public:
 	NO_COPY_CLASS(PISemaphore)
@@ -42,24 +45,24 @@ public:
 	~PISemaphore();
 
 
-	//! \~english Acquire \"cnt\" resources. If no available resources, than blocks until they freed.
-	//! \~russian Захватывает \"cnt\" ресурсов. Если свободных ресурсов недостаточно, то блокирует до их появления.
+	//! \~english Acquires \a cnt resource units, waiting until enough units become available.
+	//! \~russian Захватывает \a cnt единиц ресурса, ожидая появления достаточного количества.
 	void acquire(int cnt = 1);
 
-	//! \~english Try to acquire \"cnt\" resources. Returns if operation was successfull.
-	//! \~russian Пробует захватывает \"cnt\" ресурсов. Возвращает успех захвата.
+	//! \~english Tries to acquire \a cnt resource units without waiting.
+	//! \~russian Пытается захватить \a cnt единиц ресурса без ожидания.
 	bool tryAcquire(int cnt = 1);
 
-	//! \~english Try to acquire \"cnt\" resources for \"timeout\". Returns if operation was successfull (timeout has not expired).
-	//! \~russian Пробует захватывает \"cnt\" ресурсов в течении \"timeout\". Возвращает успех захвата (не истек ли тайм-аут).
+	//! \~english Tries to acquire \a cnt resource units within \a timeout.
+	//! \~russian Пытается захватить \a cnt единиц ресурса в пределах \a timeout.
 	bool tryAcquire(int cnt, PISystemTime timeout);
 
-	//! \~english Release \"cnt\" resources.
-	//! \~russian Освобождает \"cnt\" ресурсов.
+	//! \~english Releases \a cnt resource units and wakes waiting threads.
+	//! \~russian Освобождает \a cnt единиц ресурса и пробуждает ожидающие потоки.
 	void release(int cnt = 1);
 
-	//! \~english Returns available resources count.
-	//! \~russian Возвращает количество свободных ресурсов.
+	//! \~english Returns the current number of available resource units.
+	//! \~russian Возвращает текущее количество доступных единиц ресурса.
 	int available() const;
 
 private:
@@ -68,7 +71,10 @@ private:
 	PIConditionVariable var;
 };
 
-
+//! \~\ingroup Thread
+//! \~\brief
+//! \~english Scope guard that acquires semaphore units in constructor and releases them in destructor.
+//! \~russian Защитник области видимости, который захватывает единицы семафора в конструкторе и освобождает их в деструкторе.
 class PIP_EXPORT PISemaphoreLocker {
 public:
 	NO_COPY_CLASS(PISemaphoreLocker);
@@ -92,4 +98,4 @@ private:
 };
 
 
-#endif
+#endif // PISEMAPHORE_H