merged AI doc, some new pages

libs/main/resources/piresources.h

@@ -1,9 +1,8 @@
-/*! \file piresources.h
- * \ingroup Resources
- * \~\brief
- * \~english Resources subsystem
- * \~russian Подсистема ресурсов
- */
+//! \~\file piresources.h
+//! \~\ingroup Resources
+//! \~\brief
+//! \~english Resources subsystem
+//! \~russian Подсистема ресурсов
 /*
     PIP - Platform Independent Primitives
     Resources subsystem
@@ -48,10 +47,8 @@
 //! \~\authors
 //! \~english
 //! Ivan Pelipenko peri4ko@yandex.ru;
-//! Andrey Bychkov work.a.b@yandex.ru;
 //! \~russian
 //! Иван Пелипенко peri4ko@yandex.ru;
-//! Андрей Бычков work.a.b@yandex.ru;
 //!
 
 #ifndef PIRESOURCES_H
@@ -59,18 +56,41 @@
 
 #include "pistring.h"
 
-#define INIT_RESOURCE(name)                 \
-	{                                       \
-		extern void _pirc_##name##_init_(); \
-		_pirc_##name##_init_();             \
-	}
+#ifdef DOXYGEN
 
+//! \~\ingroup Resources
+//! \relatesalso PIResources
+//! \~\brief
+//! \~english Registers a compiled resource module in the global storage.
+//! \~russian Регистрирует в глобальном хранилище модуль со вкомпиленными ресурсами.
+#  define INIT_RESOURCE(name)
+
+#else
+
+#  define INIT_RESOURCE(name)                 \
+	  {                                       \
+		  extern void _pirc_##name##_init_(); \
+		  _pirc_##name##_init_();             \
+	  }
+
+#endif
+
+//! \~\ingroup Resources
+//! \~\brief
+//! \~english Access to resources embedded into the application binary.
+//! \~russian Доступ к ресурсам, встроенным в бинарный файл приложения.
 class PIP_EXPORT PIResources {
 public:
-	//!
+	//! \~english Returns resource data from section `section` by entry name `name`.
+	//! \~russian Возвращает данные ресурса из секции `section` по имени элемента `name`.
 	static PIByteArray get(const PIString & section, const PIString & name);
+
+	//! \~english Returns first resource with name `name` across all registered sections.
+	//! \~russian Возвращает первый ресурс с именем `name` среди всех зарегистрированных секций.
 	static PIByteArray get(const PIString & name);
 
+	//! \~english Prints registered resource sections and entry sizes.
+	//! \~russian Печатает зарегистрированные секции ресурсов и размеры элементов.
 	static void dump();
 
 private:

libs/main/resources/piresourcesstorage.h

@@ -1,3 +1,8 @@
+//! \~\file piresourcesstorage.h
+//! \~\ingroup Resources
+//! \~\brief
+//! \~english Storage for compiled resources
+//! \~russian Хранилище вкомпиленных ресурсов
 /*
     PIP - Platform Independent Primitives
     Resources subsystem
@@ -26,17 +31,41 @@
 
 class PIResources;
 
+//! \~\ingroup Resources
+//! \~\brief
+//! \~english Global storage for sections and entries registered by the resources subsystem.
+//! \~russian Глобальное хранилище секций и элементов, зарегистрированных подсистемой ресурсов.
 class PIP_EXPORT PIResourcesStorage {
 	friend class PIResources;
 
 public:
+	//! \~english Returns singleton storage instance.
+	//! \~russian Возвращает экземпляр глобального хранилища.
 	static PIResourcesStorage * instance();
 
+	//! \~\ingroup Resources
+	//! \~\brief
+	//! \~english One logical resource section with named binary entries.
+	//! \~russian Одна логическая секция ресурсов с именованными бинарными элементами.
 	struct PIP_EXPORT Section {
+		//! \~english Constructs an empty section.
+		//! \~russian Создает пустую секцию.
 		Section();
+
+		//! \~english Destroys the section object.
+		//! \~russian Уничтожает объект секции.
 		~Section();
+
+		//! \~english Adds entries from another section without replacing existing names.
+		//! \~russian Добавляет элементы из другой секции, не заменяя уже существующие имена.
 		void add(const Section & s);
+
+		//! \~english Deletes stored entry buffers and clears the section.
+		//! \~russian Удаляет сохраненные буферы элементов и очищает секцию.
 		void purge();
+
+		//! \~english Section entries indexed by resource name or alias.
+		//! \~russian Элементы секции с индексом по имени ресурса или псевдониму.
 		PIMap<PIString, PIByteArray *> entries;
 	};
 
@@ -65,12 +94,28 @@ public:
 		int flags;
 	};
 
+	//! \~english Registers or merges a ready section under name `section_name`.
+	//! \~russian Регистрирует или объединяет готовую секцию под именем `section_name`.
 	void registerSection(const PIString & section_name, const Section & data);
+
+	//! \~english Registers compiled resources from raw data and serialized descriptors.
+	//! \~russian Регистрирует вкомпиленные ресурсы из сырых данных и сериализованных дескрипторов.
 	void registerSection(const uchar * rc_data, const uchar * rc_desc, int rc_desc_size);
+
+	//! \~english Returns registered section by name, or null if it is absent.
+	//! \~russian Возвращает зарегистрированную секцию по имени или null, если она отсутствует.
 	Section * section(const PIString & section_name) const;
+
+	//! \~english Returns entry data by section and entry name.
+	//! \~russian Возвращает данные элемента по секции и имени элемента.
 	PIByteArray get(const PIString & section_name, const PIString & entry_name) const;
+
+	//! \~english Returns first entry with name `entry_name` across all sections.
+	//! \~russian Возвращает первый элемент с именем `entry_name` среди всех секций.
 	PIByteArray get(const PIString & entry_name) const;
 
+	//! \~english Removes all registered sections and entry buffers.
+	//! \~russian Удаляет все зарегистрированные секции и буферы элементов.
 	void clear();
 
 private:
@@ -106,4 +151,4 @@ BINARY_STREAM_READ(PIResourcesStorage::__RCEntry) {
 }
 
 
-#endif // PIRESOURCES_H
+#endif // PIRESOURCES_P_H