more ai generated doc with human review

libs/main/code/picodeparser.h

@@ -1,8 +1,13 @@
 /*! \file picodeparser.h
- * \ingroup Code
- * \~\brief
+ * \addtogroup Code
+ * \{
+ * \~
+ * \brief
  * \~english C++ code parser
  * \~russian Разбор C++ кода
+ * \details
+ * \~english Parser for analyzing C++ source files. Extracts information about classes, structures, enums, macros, functions, and members.
+ * \~russian Парсер для анализа C++ исходных файлов. Извлекает информацию о классах, структурах, перечислениях, макросах, функциях и членах.
  */
 /*
     PIP - Platform Independent Primitives
@@ -39,6 +44,8 @@ inline bool _isCChar(const PIString & c) {
 
 class PIP_EXPORT PICodeParser {
 public:
+	//! \~english Default constructor.
+	//! \~russian Конструктор по умолчанию.
 	PICodeParser();
 
 	enum Visibility {
@@ -63,18 +70,27 @@ public:
 	typedef PIPair<PIString, PIString> Typedef;
 	typedef PIMap<PIString, PIString> MetaMap;
 
+	//! \~english Represents a preprocessor macro.
+	//! \~russian Представляет препроцессорный макрос.
 	struct PIP_EXPORT Macro {
 		Macro(const PIString & n = PIString(), const PIString & v = PIString(), const PIStringList & a = PIStringList()) {
 			name  = n;
 			value = v;
 			args  = a;
 		}
+		//! \~english Expand macro with given arguments.
+		//! \~russian Раскрыть макрос с заданными аргументами.
+		//! \param args_ Arguments string
+		//! \param ok Output flag indicating success
+		//! \return Expanded macro value
 		PIString expand(PIString args_, bool * ok = 0) const;
 		PIString name;
 		PIString value;
 		PIStringList args;
 	};
 
+	//! \~english Represents a class/struct member variable or function.
+	//! \~russian Представляет переменную-член или функцию класса/структуры.
 	struct PIP_EXPORT Member {
 		Member() {
 			visibility  = Global;
@@ -83,6 +99,8 @@ public:
 			is_type_ptr = false;
 			attributes  = NoAttributes;
 		}
+		//! \~english Check if member is a bitfield.
+		//! \~russian Проверить, является ли член битовым полем.
 		bool isBitfield() const { return bits > 0; }
 		MetaMap meta;
 		PIString type;
@@ -97,6 +115,8 @@ public:
 		int bits;
 	};
 
+	//! \~english Represents a parsed entity (class, struct, namespace, etc.).
+	//! \~russian Представляет разобранную сущность (класс, структуру, пространство имен и т.д.).
 	struct PIP_EXPORT Entity {
 		Entity() {
 			visibility   = Global;
@@ -118,6 +138,8 @@ public:
 		PIVector<Typedef> typedefs;
 	};
 
+	//! \~english Represents an enumerator value.
+	//! \~russian Представляет значение перечисления.
 	struct PIP_EXPORT EnumeratorInfo {
 		EnumeratorInfo(const PIString & n = PIString(), int v = 0, const MetaMap & m = MetaMap()) {
 			name  = n;
@@ -129,6 +151,8 @@ public:
 		int value;
 	};
 
+	//! \~english Represents a parsed enum type.
+	//! \~russian Представляет разобранный тип перечисления.
 	struct PIP_EXPORT Enum {
 		Enum(const PIString & n = PIString()) { name = n; }
 		MetaMap meta;
@@ -136,25 +160,89 @@ public:
 		PIVector<EnumeratorInfo> members;
 	};
 
+	//! \~english Parse C++ source file.
+	//! \~russian Разбор C++ исходного файла.
+	//! \param file Path to source file
+	//! \param follow_includes Whether to follow include directives
 	void parseFile(const PIString & file, bool follow_includes = true);
+
+	//! \~english Parse multiple C++ source files.
+	//! \~russian Разбор нескольких C++ исходных файлов.
+	//! \param files List of file paths
+	//! \param follow_includes Whether to follow include directives
 	void parseFiles(const PIStringList & files, bool follow_includes = true);
+
+	//! \~english Parse C++ source from string content.
+	//! \~russian Разбор C++ исходного кода из строки.
+	//! \param fc Source code content
 	void parseFileContent(PIString fc);
 
+	//! \~english Add directory to search for include files.
+	//! \~russian Добавить директорию для поиска включаемых файлов.
+	//! \param dir Directory path
 	void includeDirectory(const PIString & dir) { includes << dir; }
+
+	//! \~english Add custom macro definition.
+	//! \~russian Добавить пользовательское определение макроса.
+	//! \param def_name Macro name
+	//! \param def_value Macro value
 	void addDefine(const PIString & def_name, const PIString & def_value) { custom_defines << Define(def_name, def_value); }
+
+	//! \~english Check if name refers to an enum type.
+	//! \~russian Проверить, является ли имя типом перечисления.
+	//! \param name Name to check
+	//! \return true if name is an enum
 	bool isEnum(const PIString & name);
+
+	//! \~english Find entity by name.
+	//! \~russian Найти сущность по имени.
+	//! \param en Entity name
+	//! \return Pointer to entity or nullptr
 	Entity * findEntityByName(const PIString & en);
+
+	//! \~english Get list of parsed files.
+	//! \~russian Получить список разобранных файлов.
+	//! \return List of file paths
 	PIStringList parsedFiles() const { return PIStringList(proc_files.toVector()); }
+
+	//! \~english Get main file path.
+	//! \~russian Получить путь к главному файлу.
+	//! \return Main file path
 	PIString mainFile() const { return main_file; }
+
+	//! \~english Get global scope entity.
+	//! \~russian Получить сущность глобальной области видимости.
+	//! \return Pointer to global entity
 	const PICodeParser::Entity * global() const { return &root_; }
 
+	//! \~english Get maximum iterations for macros substitution.
+	//! \~russian Получить максимальное количество итераций для подстановки макросов.
+	//! \return Maximum iterations count
 	int macrosSubstitutionMaxIterations() const { return macros_iter; }
+
+	//! \~english Set maximum iterations for macros substitution.
+	//! \~russian Установить максимальное количество итераций для подстановки макросов.
+	//! \param value Maximum iterations count
 	void setMacrosSubstitutionMaxIterations(int value) { macros_iter = value; }
 
+	//! \~english List of defined macros.
+	//! \~russian Список определенных макросов.
 	PIVector<Define> defines, custom_defines;
+
+	//! \~english List of macro definitions with expansion.
+	//! \~russian Список определений макросов с подстановкой.
 	PIVector<Macro> macros;
+
+	//! \~english List of enumerated types.
+	//! \~russian Список типов перечислений.
 	PIVector<Enum> enums;
+
+	//! \~english List of type definitions.
+	//! \~russian Список определений типов.
 	PIVector<Typedef> typedefs;
+
+	//! \~english List of parsed entities (classes, structs, etc.).
+	//! \~russian Список разобранных сущностей (классов, структур и т.д.).
 	PIVector<Entity *> entities;
 
 private:
@@ -195,4 +283,7 @@ private:
 	PIMap<PIString, MetaMap> tmp_meta;
 };
 
+/*! \}
+ */
+
 #endif // PICODEPARSER_H