Compare commits
3 Commits
1b5a359185
...
7cf1a1298d
| Author | SHA1 | Date | |
|---|---|---|---|
| 7cf1a1298d | |||
| e362a80f85 | |||
| 9a007d7f1e |
2
.gitignore
vendored
2
.gitignore
vendored
@@ -6,3 +6,5 @@ CMakeLists.txt.user*
|
|||||||
/include
|
/include
|
||||||
/release
|
/release
|
||||||
/build*
|
/build*
|
||||||
|
/AGENTS.md
|
||||||
|
/plans
|
||||||
|
|||||||
166
AGENTS.md
166
AGENTS.md
@@ -1,166 +0,0 @@
|
|||||||
# AGENTS.md - Agent Guidelines for PIP
|
|
||||||
|
|
||||||
This file provides guidance for agentic coding agents working on the PIP (Platform Independent Primitives) codebase.
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
PIP is a C++ cross-platform library providing platform-independent abstractions for:
|
|
||||||
- Core/Types: Strings, variants, containers, datetime, networks
|
|
||||||
- Threading: Mutexes, semaphores, thread pools, timers
|
|
||||||
- I/O: Files, serial, CAN, GPIO, SPI, Ethernet
|
|
||||||
- Math: Vectors, matrices, FFT, quaternions
|
|
||||||
- Crypto: MD5, SHA, BLAKE2, SipHash
|
|
||||||
- Compression: zlib support
|
|
||||||
- HTTP: Client and server support
|
|
||||||
- Serialization: JSON, binary, XML
|
|
||||||
|
|
||||||
## Build Commands
|
|
||||||
|
|
||||||
### Basic Build
|
|
||||||
```bash
|
|
||||||
cmake -B build
|
|
||||||
cmake --build build -j8
|
|
||||||
```
|
|
||||||
|
|
||||||
### Build with Tests
|
|
||||||
```bash
|
|
||||||
cmake -B build -DTESTS=ON
|
|
||||||
cmake --build build -j8
|
|
||||||
```
|
|
||||||
|
|
||||||
### Run Tests
|
|
||||||
```bash
|
|
||||||
ctest --test-dir build/tests # Run all tests
|
|
||||||
ctest --test-dir build/tests -R <regex> # Run specific tests matching regex
|
|
||||||
ctest --test-dir build/tests -V # Verbose output
|
|
||||||
```
|
|
||||||
|
|
||||||
To run a single test:
|
|
||||||
```bash
|
|
||||||
# Build the test executable, then run directly:
|
|
||||||
./build/tests/pip_<test_name>_test
|
|
||||||
# Or use ctest with specific test name
|
|
||||||
ctest --test-dir build/tests -R "TestName"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Other Commands
|
|
||||||
```bash
|
|
||||||
cmake --build build --target clean # Clean build
|
|
||||||
cmake --install build_pip # Install
|
|
||||||
cmake --build build --target doc # Build documentation
|
|
||||||
```
|
|
||||||
|
|
||||||
### Build Options
|
|
||||||
```bash
|
|
||||||
-DTESTS=ON # Build tests
|
|
||||||
-DCOVERAGE=ON # Build with coverage
|
|
||||||
-DICU=ON # ICU support for codepage conversion
|
|
||||||
-DSTD_IOSTREAM=ON # std::iostream operators support
|
|
||||||
-DINTROSPECTION=ON # Build with introspection
|
|
||||||
-DPIP_BUILD_CRYPT=ON # Crypt module (requires libsodium)
|
|
||||||
-DPIP_BUILD_FFTW=ON # FFT support
|
|
||||||
```
|
|
||||||
|
|
||||||
## Code Style Guidelines
|
|
||||||
|
|
||||||
### File Organization
|
|
||||||
- Header files: `libs/main/**/*.h`
|
|
||||||
- Source files: `libs/main/**/*.cpp`
|
|
||||||
- Private headers: `*_p.h`
|
|
||||||
- Tests: `tests/<module>/`
|
|
||||||
- Use Doxygen comments (`/*! ... */`) for documentation with `\brief`, `\param`, `\return`
|
|
||||||
|
|
||||||
### Naming Conventions
|
|
||||||
- **Classes**: PascalCase with `PI` prefix (e.g., `PIString`, `PIByteArray`, `PIVariant`)
|
|
||||||
- **Functions**: camelCase (e.g., `toAscii()`, `isEmpty()`, `append()`)
|
|
||||||
- **Member variables**: snake_case, or just lowercase (e.g., `array_size`, `count`)
|
|
||||||
- **Constants**: PascalCase or UPPER_SNAKE_CASE
|
|
||||||
- **Enums**: PascalCase for enum names and values
|
|
||||||
|
|
||||||
### Code Formatting
|
|
||||||
- **Indentation**: Use tabs (4 spaces equivalent) or spaces - match existing code
|
|
||||||
- **Braces**: Opening brace on same line for functions, new line for namespaces/classes
|
|
||||||
- **Includes**: System includes first, then project headers
|
|
||||||
- **Use forward declarations** where possible to reduce compile times
|
|
||||||
- **Use `nullptr`** instead of `NULL`
|
|
||||||
|
|
||||||
### C++ Standards
|
|
||||||
- C++11 standard (enforced in CMakeLists.txt)
|
|
||||||
- Use `override` keyword for virtual function overrides
|
|
||||||
- Use `explicit` for single-argument constructors
|
|
||||||
- Use `const` member functions where applicable
|
|
||||||
- Use range-based `for` loops when possible
|
|
||||||
|
|
||||||
### Error Handling
|
|
||||||
- Return error codes
|
|
||||||
- DO NOT USE exceptions
|
|
||||||
- Use `piCerr` and `piCout` for error messages
|
|
||||||
- Check for null pointers where appropriate
|
|
||||||
|
|
||||||
### Module Structure
|
|
||||||
|
|
||||||
Each module typically has:
|
|
||||||
1. Public header: `pip_<module>.h` or `<classname>.h`
|
|
||||||
2. Private implementation: `<classname>.cpp` or `<classname>_p.cpp`
|
|
||||||
3. Use `PIP_EXPORT` macro for symbols that need to be exported from the library
|
|
||||||
|
|
||||||
Example class structure:
|
|
||||||
```cpp
|
|
||||||
// header.h
|
|
||||||
#ifndef MODULE_CLASSNAME_H
|
|
||||||
#define MODULE_CLASSNAME_H
|
|
||||||
|
|
||||||
#include "pip_export.h"
|
|
||||||
|
|
||||||
class PIP_EXPORT ClassName {
|
|
||||||
public:
|
|
||||||
ClassName();
|
|
||||||
~ClassName();
|
|
||||||
|
|
||||||
void doSomething();
|
|
||||||
bool isValid() const;
|
|
||||||
|
|
||||||
private:
|
|
||||||
void privateMethod();
|
|
||||||
int data;
|
|
||||||
};
|
|
||||||
|
|
||||||
#endif // MODULE_CLASSNAME_H
|
|
||||||
|
|
||||||
// source.cpp
|
|
||||||
#include "header.h"
|
|
||||||
#include "piincludes_p.h"
|
|
||||||
|
|
||||||
ClassName::ClassName() : data(0) {}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Testing
|
|
||||||
- Use Google Test framework
|
|
||||||
- Test files go in `tests/<module>/`
|
|
||||||
- Use `TEST(TestSuite, TestName)` or `TEST_F(TestFixture, TestName)` for test cases
|
|
||||||
- Use `ASSERT_*` for fatal failures, `EXPECT_*` for non-fatal
|
|
||||||
- Test naming: `<ClassName>_<TestDescription>`
|
|
||||||
|
|
||||||
Example:
|
|
||||||
```cpp
|
|
||||||
#include "pistring.h"
|
|
||||||
#include "gtest/gtest.h"
|
|
||||||
|
|
||||||
TEST(PIString_Tests, constructor_empty) {
|
|
||||||
PIString str;
|
|
||||||
ASSERT_TRUE(str.isEmpty());
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Module Dependencies
|
|
||||||
- Main library: `libs/main/`
|
|
||||||
- Third-party: `3rd/`
|
|
||||||
- Utils: `utils/`
|
|
||||||
|
|
||||||
### Key Files
|
|
||||||
- `CMakeLists.txt` - Main build configuration
|
|
||||||
- `tests/CMakeLists.txt` - Test configuration
|
|
||||||
|
|
||||||
|
|
||||||
## Lint/Format Commands
|
|
||||||
- For formatting, use clang-format with .clang-format in repo root
|
|
||||||
@@ -5,8 +5,8 @@ if (POLICY CMP0177)
|
|||||||
endif()
|
endif()
|
||||||
project(PIP)
|
project(PIP)
|
||||||
set(PIP_MAJOR 5)
|
set(PIP_MAJOR 5)
|
||||||
set(PIP_MINOR 5)
|
set(PIP_MINOR 6)
|
||||||
set(PIP_REVISION 5)
|
set(PIP_REVISION 0)
|
||||||
set(PIP_SUFFIX )
|
set(PIP_SUFFIX )
|
||||||
set(PIP_COMPANY SHS)
|
set(PIP_COMPANY SHS)
|
||||||
set(PIP_DOMAIN org.SHS)
|
set(PIP_DOMAIN org.SHS)
|
||||||
|
|||||||
115
README.md
115
README.md
@@ -40,3 +40,118 @@ You should add ${<out_var>} to your target.
|
|||||||
[🇷🇺 Онлайн документация](https://shstk.ru/pip/html/ru/index.html)
|
[🇷🇺 Онлайн документация](https://shstk.ru/pip/html/ru/index.html)
|
||||||
|
|
||||||
[🇷🇺 Qt-help](https://shstk.ru/pip/pip_ru.qch)
|
[🇷🇺 Qt-help](https://shstk.ru/pip/pip_ru.qch)
|
||||||
|
|
||||||
|
## Основные опции сборки
|
||||||
|
|
||||||
|
### Стандартные опции (option())
|
||||||
|
| Опция | Описание | По умолчанию |
|
||||||
|
|-------|----------|--------------|
|
||||||
|
| `ICU` | ICU support для конвертации кодовых страниц | ON (кроме Win/Android/Apple) |
|
||||||
|
| `STD_IOSTREAM` | Поддержка std::iostream операторов | OFF |
|
||||||
|
| `INTROSPECTION` | Сборка с интроспекцией | OFF |
|
||||||
|
| `TESTS` | Сборка тестов | OFF |
|
||||||
|
| `COVERAGE` | Сборка с информацией о покрытии | OFF |
|
||||||
|
| `PIP_FFTW_F` | Поддержка FFTW для float | ON |
|
||||||
|
| `PIP_FFTW_L` | Поддержка FFTW для long double | ON |
|
||||||
|
| `PIP_FFTW_Q` | Поддержка FFTW для quad double | OFF |
|
||||||
|
|
||||||
|
### Опции модулей (PIP_BUILD_*)
|
||||||
|
| Опция | Модуль |
|
||||||
|
|-------|--------|
|
||||||
|
| `PIP_BUILD_CONSOLE` | console |
|
||||||
|
| `PIP_BUILD_CRYPT` | crypt (требует libsodium) |
|
||||||
|
| `PIP_BUILD_COMPRESS` | compress (требует zlib) |
|
||||||
|
| `PIP_BUILD_USB` | usb |
|
||||||
|
| `PIP_BUILD_FFTW` | fftw |
|
||||||
|
| `PIP_BUILD_OPENCL` | opencl |
|
||||||
|
| `PIP_BUILD_IO_UTILS` | io_utils |
|
||||||
|
| `PIP_BUILD_CLIENT_SERVER` | client_server |
|
||||||
|
| `PIP_BUILD_CLOUD` | cloud |
|
||||||
|
| `PIP_BUILD_LUA` | lua |
|
||||||
|
| `PIP_BUILD_HTTP_CLIENT` | http_client (требует libcurl) |
|
||||||
|
| `PIP_BUILD_HTTP_SERVER` | http_server (требует libmicrohttpd) |
|
||||||
|
|
||||||
|
### Дополнительные переменные
|
||||||
|
| Переменная | Описание |
|
||||||
|
|------------|----------|
|
||||||
|
| `PIP_BUILD_DEBUG` | Сборка debug версии |
|
||||||
|
| `PIP_FREERTOS` | Режим сборки для FreeRTOS |
|
||||||
|
| `CROSSTOOLS` | Собрать инструменты кросс-сборки под хостовую систему (pip_cmg, pip_rc, ...) |
|
||||||
|
| `LOCAL` | Локальная установка (bin/lib/include) |
|
||||||
|
| `PIP_CONTAINERS_MIN_ALLOC` | Переопределить минимальный размер аллокации контейнеров |
|
||||||
|
| `PIP_CONTAINERS_MAX_POT_ALLOC` | Переопределить максимальный размер дополнительной аллокации (поддерживает X_KiB, X_MiB) |
|
||||||
|
|
||||||
|
### Примеры использования
|
||||||
|
```bash
|
||||||
|
# Базовая сборка с тестами
|
||||||
|
cmake -B build -DTESTS=ON
|
||||||
|
|
||||||
|
# Сборка с покрытием и ICU
|
||||||
|
cmake -B build -DTESTS=ON -DCOVERAGE=ON -DICU=ON
|
||||||
|
|
||||||
|
# Отключение отдельных модулей
|
||||||
|
cmake -B build -DPIP_BUILD_CRYPT=OFF -DPIP_BUILD_OPENCL=OFF
|
||||||
|
|
||||||
|
# Переопределение параметров контейнеров
|
||||||
|
cmake -B build -DPIP_CONTAINERS_MIN_ALLOC=64
|
||||||
|
|
||||||
|
# Локальная установка
|
||||||
|
cmake -B build -DLOCAL=ON
|
||||||
|
```
|
||||||
|
|
||||||
|
## PIP Dependencies
|
||||||
|
|
||||||
|
### Встроенные (included in 3rd/)
|
||||||
|
|
||||||
|
| Библиотека | Назначение | Модуль PIP |
|
||||||
|
|------------|------------|------------|
|
||||||
|
| **PCRE2** | Регулярные выражения | main (internal) |
|
||||||
|
| **BLAKE2** | Хеширование | main (internal) |
|
||||||
|
| **SipHash** | Хеширование | main (internal) |
|
||||||
|
| **Lua** | Lua scripting | lua |
|
||||||
|
| **LuaBridge** | Lua bindings | lua |
|
||||||
|
|
||||||
|
### Внешние (системные)
|
||||||
|
|
||||||
|
| Библиотека | Опция | Модуль PIP |
|
||||||
|
|------------|-------|------------|
|
||||||
|
| **ICU** | `-DICU=ON` | main (string conversion) |
|
||||||
|
| **zlib** | `PIP_BUILD_COMPRESS` | compress |
|
||||||
|
| **libsodium** | `PIP_BUILD_CRYPT` | crypt, io_utils, cloud |
|
||||||
|
| **libusb** | `PIP_BUILD_USB` | usb |
|
||||||
|
| **FFTW3** (+ threads) | `PIP_BUILD_FFTW` | fftw |
|
||||||
|
| **OpenCL** | `PIP_BUILD_OPENCL` | opencl |
|
||||||
|
| **libmicrohttpd** | `PIP_BUILD_HTTP_SERVER` | http_server |
|
||||||
|
| **libcurl** | `PIP_BUILD_HTTP_CLIENT` | http_client |
|
||||||
|
|
||||||
|
### Опциональные (тесты/документация)
|
||||||
|
|
||||||
|
| Инструмент | Назначение |
|
||||||
|
|------------|------------|
|
||||||
|
| **Google Test** | Тестирование (fetched automatically) |
|
||||||
|
| **Doxygen** | Генерация документации |
|
||||||
|
|
||||||
|
|
||||||
|
### Схема зависимостей модулей
|
||||||
|
|
||||||
|
```
|
||||||
|
main (core)
|
||||||
|
├── PCRE2 (встроен)
|
||||||
|
├── BLAKE2 (встроен)
|
||||||
|
├── SipHash (встроен)
|
||||||
|
└── ICU (опционально)
|
||||||
|
|
||||||
|
console → main
|
||||||
|
compress → zlib
|
||||||
|
crypt → libsodium
|
||||||
|
usb → libusb
|
||||||
|
fftw → FFTW3
|
||||||
|
opencl → OpenCL
|
||||||
|
io_utils → [crypt, если доступен]
|
||||||
|
client_server → io_utils
|
||||||
|
cloud → io_utils, crypt
|
||||||
|
lua → Lua (встроен), LuaBridge (встроен)
|
||||||
|
http_server → libmicrohttpd
|
||||||
|
http_client → libcurl
|
||||||
|
```
|
||||||
|
|
||||||
|
|||||||
@@ -1,70 +0,0 @@
|
|||||||
# PIP Dependencies
|
|
||||||
|
|
||||||
## Встроенные (included in 3rd/)
|
|
||||||
|
|
||||||
| Библиотека | Назначение | Модуль PIP |
|
|
||||||
|------------|------------|------------|
|
|
||||||
| **PCRE2** | Регулярные выражения | main (internal) |
|
|
||||||
| **BLAKE2** | Хеширование | main (internal) |
|
|
||||||
| **SipHash** | Хеширование | main (internal) |
|
|
||||||
| **Lua** | Lua scripting | lua |
|
|
||||||
| **LuaBridge** | Lua bindings | lua |
|
|
||||||
|
|
||||||
## Внешние (системные)
|
|
||||||
|
|
||||||
| Библиотека | Опция | Модуль PIP |
|
|
||||||
|------------|-------|------------|
|
|
||||||
| **ICU** | `-DICU=ON` | main (string conversion) |
|
|
||||||
| **zlib** | `PIP_BUILD_COMPRESS` | compress |
|
|
||||||
| **libsodium** | `PIP_BUILD_CRYPT` | crypt, io_utils, cloud |
|
|
||||||
| **libusb** | `PIP_BUILD_USB` | usb |
|
|
||||||
| **FFTW3** (+ threads) | `PIP_BUILD_FFTW` | fftw |
|
|
||||||
| **OpenCL** | `PIP_BUILD_OPENCL` | opencl |
|
|
||||||
| **libmicrohttpd** | `PIP_BUILD_HTTP_SERVER` | http_server |
|
|
||||||
| **libcurl** | `PIP_BUILD_HTTP_CLIENT` | http_client |
|
|
||||||
| **gnutls** | (optional, для http_server) | http_server |
|
|
||||||
| **pthread** | (system) | main |
|
|
||||||
| **libdl** | (system) | main |
|
|
||||||
| **librt** | (system, не Apple/Android) | main |
|
|
||||||
| **libutil** | (system) | main |
|
|
||||||
| **libsocket** | (QNX) | main |
|
|
||||||
| **ws2_32, iphlpapi, psapi, cfgmgr32, setupapi, hid** | (Windows) | main |
|
|
||||||
|
|
||||||
## Опциональные (тесты/документация)
|
|
||||||
|
|
||||||
| Инструмент | Назначение |
|
|
||||||
|------------|------------|
|
|
||||||
| **Google Test** | Тестирование (fetched automatically) |
|
|
||||||
| **Doxygen** | Генерация документации |
|
|
||||||
|
|
||||||
## Стандартные системные библиотеки
|
|
||||||
|
|
||||||
- libm (math)
|
|
||||||
- libc (C standard)
|
|
||||||
|
|
||||||
## Схема зависимостей модулей
|
|
||||||
|
|
||||||
```
|
|
||||||
main (core)
|
|
||||||
├── PCRE2 (встроен)
|
|
||||||
├── BLAKE2 (встроен)
|
|
||||||
├── SipHash (встроен)
|
|
||||||
├── pthread (система)
|
|
||||||
├── libdl (система)
|
|
||||||
├── librt (система)
|
|
||||||
├── libutil (система)
|
|
||||||
└── ICU (опционально)
|
|
||||||
|
|
||||||
console → main
|
|
||||||
compress → zlib
|
|
||||||
crypt → libsodium
|
|
||||||
usb → libusb
|
|
||||||
fftw → FFTW3
|
|
||||||
opencl → OpenCL
|
|
||||||
io_utils → [crypt, если доступен]
|
|
||||||
client_server → io_utils
|
|
||||||
cloud → io_utils, crypt
|
|
||||||
lua → Lua (встроен), LuaBridge (встроен)
|
|
||||||
http_server → libmicrohttpd, [gnutls]
|
|
||||||
http_client → libcurl
|
|
||||||
```
|
|
||||||
59
options.md
59
options.md
@@ -1,59 +0,0 @@
|
|||||||
# PIP Build Options
|
|
||||||
|
|
||||||
## Основные опции сборки
|
|
||||||
|
|
||||||
### Стандартные опции (option())
|
|
||||||
| Опция | Описание | По умолчанию |
|
|
||||||
|-------|----------|--------------|
|
|
||||||
| `ICU` | ICU support для конвертации кодовых страниц | ON (кроме Win/Android/Apple) |
|
|
||||||
| `STD_IOSTREAM` | Поддержка std::iostream операторов | OFF |
|
|
||||||
| `INTROSPECTION` | Сборка с интроспекцией | OFF |
|
|
||||||
| `TESTS` | Сборка тестов | OFF |
|
|
||||||
| `COVERAGE` | Сборка с информацией о покрытии | OFF |
|
|
||||||
| `PIP_FFTW_F` | Поддержка FFTW для float | ON |
|
|
||||||
| `PIP_FFTW_L` | Поддержка FFTW для long double | ON |
|
|
||||||
| `PIP_FFTW_Q` | Поддержка FFTW для quad double | OFF |
|
|
||||||
|
|
||||||
### Опции модулей (PIP_BUILD_*)
|
|
||||||
| Опция | Модуль |
|
|
||||||
|-------|--------|
|
|
||||||
| `PIP_BUILD_CONSOLE` | console |
|
|
||||||
| `PIP_BUILD_CRYPT` | crypt (требует libsodium) |
|
|
||||||
| `PIP_BUILD_COMPRESS` | compress (требует zlib) |
|
|
||||||
| `PIP_BUILD_USB` | usb |
|
|
||||||
| `PIP_BUILD_FFTW` | fftw |
|
|
||||||
| `PIP_BUILD_OPENCL` | opencl |
|
|
||||||
| `PIP_BUILD_IO_UTILS` | io_utils |
|
|
||||||
| `PIP_BUILD_CLIENT_SERVER` | client_server |
|
|
||||||
| `PIP_BUILD_CLOUD` | cloud |
|
|
||||||
| `PIP_BUILD_LUA` | lua |
|
|
||||||
| `PIP_BUILD_HTTP_CLIENT` | http_client (требует libcurl) |
|
|
||||||
| `PIP_BUILD_HTTP_SERVER` | http_server (требует libmicrohttpd) |
|
|
||||||
|
|
||||||
### Дополнительные переменные
|
|
||||||
| Переменная | Описание |
|
|
||||||
|------------|----------|
|
|
||||||
| `PIP_BUILD_DEBUG` | Сборка debug версии |
|
|
||||||
| `PIP_FREERTOS` | Поддержка FreeRTOS |
|
|
||||||
| `CROSSTOOLS` | Режим кросс-компиляции |
|
|
||||||
| `LOCAL` | Локальная установка (bin/lib/include) |
|
|
||||||
| `PIP_CONTAINERS_MIN_ALLOC` | Переопределить минимальный размер аллокации контейнеров |
|
|
||||||
| `PIP_CONTAINERS_MAX_POT_ALLOC` | Переопределить максимальный размер (поддерживает X_KiB, X_MiB) |
|
|
||||||
|
|
||||||
### Примеры использования
|
|
||||||
```bash
|
|
||||||
# Базовая сборка с тестами
|
|
||||||
cmake -B build -DTESTS=ON
|
|
||||||
|
|
||||||
# Сборка с покрытием и ICU
|
|
||||||
cmake -B build -DTESTS=ON -DCOVERAGE=ON -DICU=ON
|
|
||||||
|
|
||||||
# Отключение отдельных модулей
|
|
||||||
cmake -B build -DPIP_BUILD_CRYPT=OFF -DPIP_BUILD_OPENCL=OFF
|
|
||||||
|
|
||||||
# Переопределение параметров контейнеров
|
|
||||||
cmake -B build -DPIP_CONTAINERS_MIN_ALLOC=64
|
|
||||||
|
|
||||||
# Локальная установка
|
|
||||||
cmake -B build -DLOCAL=ON
|
|
||||||
```
|
|
||||||
@@ -1,337 +0,0 @@
|
|||||||
# План: Добавление документации Doxygen в заголовочные файлы PIP
|
|
||||||
|
|
||||||
## Обзор
|
|
||||||
|
|
||||||
Необходимо добавить базовую документацию Doxygen (`\brief`) во все публичные заголовочные файлы проекта. Каждый файл должен содержать:
|
|
||||||
- Документацию в начале файла (`\file`, `\brief`, группа)
|
|
||||||
- Документацию для каждого класса (`\class`, `\brief`)
|
|
||||||
- Документацию для всех публичных методов (`\brief`)
|
|
||||||
|
|
||||||
## Стиль документации
|
|
||||||
|
|
||||||
Используется два стиля комментариев (оба поддерживаются):
|
|
||||||
1. `//!` - однострочные комментарии (предпочтительно)
|
|
||||||
2. `/*! ... */` - многострочные блоки
|
|
||||||
|
|
||||||
## Пример оформления (на основе pipair.h)
|
|
||||||
|
|
||||||
```cpp
|
|
||||||
//! \addtogroup Containers
|
|
||||||
//! \{
|
|
||||||
//! \file pipair.h
|
|
||||||
//! \brief
|
|
||||||
//! \~english Declares \a PIPair
|
|
||||||
//! \~russian Объявление \a PIPair
|
|
||||||
//! \~\authors
|
|
||||||
//! \~english Ivan Pelipenko peri4ko@yandex.ru; Andrey Bychkov work.a.b@yandex.ru
|
|
||||||
//! \~russian Иван Пелипенко peri4ko@yandex.ru; Андрей Бычков work.a.b@yandex.ru
|
|
||||||
//! \~\}
|
|
||||||
/*
|
|
||||||
Лицензия GPL
|
|
||||||
*/
|
|
||||||
|
|
||||||
#ifndef PIPAIR_H
|
|
||||||
#define PIPAIR_H
|
|
||||||
|
|
||||||
#include "picout.h"
|
|
||||||
|
|
||||||
//! \addtogroup Containers
|
|
||||||
//! \{
|
|
||||||
//! \class PIPair
|
|
||||||
//! \brief
|
|
||||||
//! \~english Class template that provides a way to store two heterogeneous objects as a single unit.
|
|
||||||
//! \~russian Класс, который позволяет хранить два разнородных объекта как единое целое.
|
|
||||||
//! \~\}
|
|
||||||
//! \~\sa \a PIMap
|
|
||||||
template<typename Type0, typename Type1>
|
|
||||||
class PIPair {
|
|
||||||
public:
|
|
||||||
//! \~english Constructs an empty PIPair.
|
|
||||||
//! \~russian Создает пустой PIPair.
|
|
||||||
PIPair(): first(), second() {}
|
|
||||||
|
|
||||||
//! \~english Constructs PIPair from values `value0` and `value1`.
|
|
||||||
//! \~russian Создает PIPair из `value0` и `value1`.
|
|
||||||
PIPair(const Type0 & value0, const Type1 & value1) {
|
|
||||||
first = value0;
|
|
||||||
second = value1;
|
|
||||||
}
|
|
||||||
|
|
||||||
//! \~english First element.
|
|
||||||
//! \~russian Первый элемент.
|
|
||||||
Type0 first;
|
|
||||||
|
|
||||||
//! \~english Second element.
|
|
||||||
//! \~russian Второй элемент.
|
|
||||||
Type1 second;
|
|
||||||
};
|
|
||||||
|
|
||||||
//! \~english Compare operator with PIPair.
|
|
||||||
//! \~russian Оператор сравнения с PIPair.
|
|
||||||
template<typename Type0, typename Type1>
|
|
||||||
inline bool operator==(const PIPair<Type0, Type1> & value0, const PIPair<Type0, Type1> & value1) {
|
|
||||||
return (value0.first == value1.first) && (value0.second == value1.second);
|
|
||||||
}
|
|
||||||
|
|
||||||
#endif // PIPAIR_H
|
|
||||||
```
|
|
||||||
|
|
||||||
## Инструкции для агента (на один файл)
|
|
||||||
|
|
||||||
1. **Прочитать файл** и определить:
|
|
||||||
- Группу модуля (Container, Types, Core, IO, Thread, Math и т.д.)
|
|
||||||
- Все классы в файле
|
|
||||||
- Все публичные методы каждого класса
|
|
||||||
- Все свободные функции (non-member)
|
|
||||||
|
|
||||||
2. **Добавить документацию в начале файла** (если отсутствует):
|
|
||||||
```cpp
|
|
||||||
//! \addtogroup <GroupName>
|
|
||||||
//! \{
|
|
||||||
//! \file <filename>
|
|
||||||
//! \brief
|
|
||||||
//! \~english Brief description
|
|
||||||
//! \~russian Краткое описание
|
|
||||||
//! \~\}
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Добавить документацию для каждого класса**:
|
|
||||||
```cpp
|
|
||||||
//! \class ClassName
|
|
||||||
//! \brief
|
|
||||||
//! \~english Class description
|
|
||||||
//! \~russian Описание класса
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Добавить документацию для методов**:
|
|
||||||
```cpp
|
|
||||||
//! \~english Method description.
|
|
||||||
//! \~russian Описание метода.
|
|
||||||
ReturnType methodName(params);
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Проверить, что файл компилируется** после изменений
|
|
||||||
|
|
||||||
## Список файлов для обработки
|
|
||||||
|
|
||||||
### Containers (11 файлов)
|
|
||||||
- libs/main/containers/picollections.h
|
|
||||||
- libs/main/containers/picontainersmodule.h
|
|
||||||
- libs/main/containers/pideque.h
|
|
||||||
- libs/main/containers/pimap.h
|
|
||||||
- libs/main/containers/pipair.h
|
|
||||||
- libs/main/containers/piqueue.h
|
|
||||||
- libs/main/containers/piset.h
|
|
||||||
- libs/main/containers/pistack.h
|
|
||||||
- libs/main/containers/pivector.h
|
|
||||||
- libs/main/containers/pivector2d.h
|
|
||||||
|
|
||||||
### Core (11 файлов)
|
|
||||||
- libs/main/core/pibase.h
|
|
||||||
- libs/main/core/pibase_macros.h
|
|
||||||
- libs/main/core/picoremodule.h
|
|
||||||
- libs/main/core/picout.h
|
|
||||||
- libs/main/core/piincludes.h
|
|
||||||
- libs/main/core/piincludes_p.h
|
|
||||||
- libs/main/core/piinit.h
|
|
||||||
- libs/main/core/pimemoryblock.h
|
|
||||||
- libs/main/core/piobject.h
|
|
||||||
- libs/main/core/piobject_macros.h
|
|
||||||
- libs/main/core/piwaitevent_p.h
|
|
||||||
|
|
||||||
### Types (17 файлов)
|
|
||||||
- libs/main/types/pibitarray.h
|
|
||||||
- libs/main/types/pibytearray.h
|
|
||||||
- libs/main/types/pidatetime.h
|
|
||||||
- libs/main/types/piflags.h
|
|
||||||
- libs/main/types/pinetworkaddress.h
|
|
||||||
- libs/main/types/pipropertystorage.h
|
|
||||||
- libs/main/types/pisystemtime.h
|
|
||||||
- libs/main/types/pitime.h
|
|
||||||
- libs/main/types/pitypesmodule.h
|
|
||||||
- libs/main/types/pivaluetree.h
|
|
||||||
- libs/main/types/pivariant.h
|
|
||||||
- libs/main/types/pivarianttypes.h
|
|
||||||
- libs/main/types/pivariantsimple.h
|
|
||||||
- libs/main/types/pinetworkaddress.h
|
|
||||||
- libs/main/types/colors_p.h
|
|
||||||
- libs/main/types/pipropertystorage.h
|
|
||||||
|
|
||||||
### Text (7 файлов)
|
|
||||||
- libs/main/text/pichar.h
|
|
||||||
- libs/main/text/piconstchars.h
|
|
||||||
- libs/main/text/piregularexpression.h
|
|
||||||
- libs/main/text/pistring.h
|
|
||||||
- libs/main/text/pistringlist.h
|
|
||||||
- libs/main/text/pitextmodule.h
|
|
||||||
- libs/main/text/pitextstream.h
|
|
||||||
|
|
||||||
### IO Devices (20+ файлов)
|
|
||||||
- libs/main/io_devices/pibinarylog.h
|
|
||||||
- libs/main/io_devices/pican.h
|
|
||||||
- libs/main/io_devices/piconfig.h
|
|
||||||
- libs/main/io_devices/pidir.h
|
|
||||||
- libs/main/io_devices/piethernet.h
|
|
||||||
- libs/main/io_devices/pifile.h
|
|
||||||
- libs/main/io_devices/pigpio.h
|
|
||||||
- libs/main/io_devices/piiobytearray.h
|
|
||||||
- libs/main/io_devices/piiodevice.h
|
|
||||||
- libs/main/io_devices/piiodevicesmodule.h
|
|
||||||
- libs/main/io_devices/piiostream.h
|
|
||||||
- libs/main/io_devices/piiostring.h
|
|
||||||
- libs/main/io_devicespipeer.h
|
|
||||||
- libs/main/io_devices/piserial.h
|
|
||||||
- libs/main/io_devices/pisharedmemory.h
|
|
||||||
- libs/main/io_devices/pispi.h
|
|
||||||
- libs/main/io_devices/pitransparentdevice.h
|
|
||||||
- libs/main/io_devices/piusb.h
|
|
||||||
|
|
||||||
### Thread (18 файлов)
|
|
||||||
- libs/main/thread/piblockingqueue.h
|
|
||||||
- libs/main/thread/piconditionvar.h
|
|
||||||
- libs/main/thread/pigrabberbase.h
|
|
||||||
- libs/main/thread/pimutex.h
|
|
||||||
- libs/main/thread/pipipelinethread.h
|
|
||||||
- libs/main/thread/piprotectedvariable.h
|
|
||||||
- libs/main/thread/pireadwritelock.h
|
|
||||||
- libs/main/thread/pisemaphore.h
|
|
||||||
- libs/main/thread/pispinlock.h
|
|
||||||
- libs/main/thread/pithread.h
|
|
||||||
- libs/main/thread/pithreadmodule.h
|
|
||||||
- libs/main/thread/pithreadnotifier.h
|
|
||||||
- libs/main/thread/pithreadpoolloop.h
|
|
||||||
- libs/main/thread/pithreadpoolexecutor.h
|
|
||||||
- libs/main/thread/pitimer.h
|
|
||||||
|
|
||||||
### Math (14 файлов)
|
|
||||||
- libs/main/math/picrc.h
|
|
||||||
- libs/main/math/pievaluator.h
|
|
||||||
- libs/main/math/pifft.h
|
|
||||||
- libs/main/math/pigeometry.h
|
|
||||||
- libs/main/math/piline.h
|
|
||||||
- libs/main/math/pimatcomplex.h
|
|
||||||
- libs/main/math/pimatvector.h
|
|
||||||
- libs/main/math/pimatmatrix.h
|
|
||||||
- libs/main/math/pimathsolver.h
|
|
||||||
- libs/main/math/pimathbase.h
|
|
||||||
- libs/main/math/pimathmodule.h
|
|
||||||
- libs/main/math/piquantaternion.h
|
|
||||||
- libs/main/math/pirect.h
|
|
||||||
- libs/main/math/pistatistic.h
|
|
||||||
|
|
||||||
### Crypt (3 файла)
|
|
||||||
- libs/main/crypt/piauth.h
|
|
||||||
- libs/main/crypt/picrypt.h
|
|
||||||
- libs/main/crypt/picryptmodule.h
|
|
||||||
|
|
||||||
### Digest (1 файл)
|
|
||||||
- libs/main/digest/pidigest.h
|
|
||||||
|
|
||||||
### Serialization (7 файлов)
|
|
||||||
- libs/main/serialization/pibinarystream.h
|
|
||||||
- libs/main/serialization/pichunkstream.h
|
|
||||||
- libs/main/serialization/pijson.h
|
|
||||||
- libs/main/serialization/pijsonserialization.h
|
|
||||||
- libs/main/serialization/piserializationmodule.h
|
|
||||||
- libs/main/serialization/pivaluetree_conversions.h
|
|
||||||
- libs/main/serialization/pijson.h
|
|
||||||
|
|
||||||
### HTTP (6 файлов)
|
|
||||||
- libs/main/http_client/pihttpclient.h
|
|
||||||
- libs/main/http_client/pihttpclientmodule.h
|
|
||||||
- libs/main/http_server/pihttpserver.h
|
|
||||||
- libs/main/http_server/pihttpservermodule.h
|
|
||||||
- libs/main/http_server/microhttpd_server.h
|
|
||||||
- libs/main/http_common/pihttptypes.h
|
|
||||||
|
|
||||||
### State Machine (4 файла)
|
|
||||||
- libs/main/state_machine/pistatemachinebase.h
|
|
||||||
- libs/main/state_machine/pistatemachinestate.h
|
|
||||||
- libs/main/state_machine/pistatemachinetransition.h
|
|
||||||
- libs/main/state_machine/pistatemachinemodule.h
|
|
||||||
|
|
||||||
### System (11 файлов)
|
|
||||||
- libs/main/system/pihidevice.h
|
|
||||||
- libs/main/system/pilibrary.h
|
|
||||||
- libs/main/system/piprocess.h
|
|
||||||
- libs/main/system/piplugin.h
|
|
||||||
- libs/main/system/pisignals.h
|
|
||||||
- libs/main/system/pisysteminfo.h
|
|
||||||
- libs/main/system/pisystemmodule.h
|
|
||||||
- libs/main/system/pisystemtests.h
|
|
||||||
|
|
||||||
### Cloud (5 файлов)
|
|
||||||
- libs/main/cloud/picloudbase.h
|
|
||||||
- libs/main/cloud/picloudclient.h
|
|
||||||
- libs/main/cloud/picloudmodule.h
|
|
||||||
- libs/main/cloud/picloudserver.h
|
|
||||||
- libs/main/cloud/picloudtcp.h
|
|
||||||
|
|
||||||
### Client/Server (4 файла)
|
|
||||||
- libs/main/client_server/piclientserver_client.h
|
|
||||||
- libs/main/client_server/piclientserver_client_base.h
|
|
||||||
- libs/main/client_server/piclientserver_module.h
|
|
||||||
- libs/main/client_server/piclientserver_server.h
|
|
||||||
|
|
||||||
### Console (9 файлов)
|
|
||||||
- libs/main/console/piconsolemodule.h
|
|
||||||
- libs/main/console/pikbdlistener.h
|
|
||||||
- libs/main/console/piscreen.h
|
|
||||||
- libs/main/console/piscreenconsole.h
|
|
||||||
- libs/main/console/piscreendrawer.h
|
|
||||||
- libs/main/console/piscreentile.h
|
|
||||||
- libs/main/console/piscreentiles.h
|
|
||||||
- libs/main/console/piscreentypes.h
|
|
||||||
- libs/main/console/piterminal.h
|
|
||||||
|
|
||||||
### Resources (3 файла)
|
|
||||||
- libs/main/resources/piresources.h
|
|
||||||
- libs/main/resources/piresourcesstorage.h
|
|
||||||
|
|
||||||
### Application (3 файла)
|
|
||||||
- libs/main/application/piapplication.h
|
|
||||||
- libs/main/application/pimain.h
|
|
||||||
|
|
||||||
### Literals (6 файлов)
|
|
||||||
- libs/main/literals/piliterals.h
|
|
||||||
- libs/main/literals/piliterals_bytearray.h
|
|
||||||
- libs/main/literals/piliterals_bytes.h
|
|
||||||
- libs/main/literals/piliterals_regularexpression.h
|
|
||||||
- libs/main/literals/piliterals_string.h
|
|
||||||
- libs/main/literals/piliterals_time.h
|
|
||||||
|
|
||||||
### Geo (4 файла)
|
|
||||||
- libs/main/geo/piellipsoidmodel.h
|
|
||||||
- libs/main/geo/pigeomodule.h
|
|
||||||
- libs/main/geo/pigeoposition.h
|
|
||||||
|
|
||||||
### Units (много файлов)
|
|
||||||
- libs/main/units/piunits.h
|
|
||||||
- libs/main/units/piunits_base.h
|
|
||||||
- libs/main/units/piunits_class_angle.h
|
|
||||||
- libs/main/units/piunits_class_distance.h
|
|
||||||
- libs/main/units/piunits_class_information.h
|
|
||||||
- libs/main/units/piunits_class_mass.h
|
|
||||||
- libs/main/units/piunits_class_pressure.h
|
|
||||||
- libs/main/units/piunits_class_temperature.h
|
|
||||||
- libs/main/units/piunits_class_time.h
|
|
||||||
- libs/main/units/piunits_prefix.h
|
|
||||||
- libs/main/units/piunits_value.h
|
|
||||||
|
|
||||||
### Code (3 файла)
|
|
||||||
- libs/main/code/picodeparser.h
|
|
||||||
- libs/main/code/picodeinfo.h
|
|
||||||
- libs/main/code/picodemodule.h
|
|
||||||
|
|
||||||
### Compression (1 файл)
|
|
||||||
- libs/main/compress/picompress.h
|
|
||||||
|
|
||||||
### OpenCL (1 файл)
|
|
||||||
- libs/main/opencl/piopencl.h
|
|
||||||
|
|
||||||
### Другие модули
|
|
||||||
- libs/main/pip.h
|
|
||||||
- libs/main/piplatform.h
|
|
||||||
- libs/main/literals/piliterals.h
|
|
||||||
- libs/main/code/picodeparser.h
|
|
||||||
- libs/main/cloud/picloudtcp.h
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
Ключевые элементы документации
|
|
||||||
|
|
||||||
| Элемент | Описание |
|
|
||||||
|---------|----------|
|
|
||||||
| //! \~english | Описание на английском языке |
|
|
||||||
| //! \~russian | Описание на русском языке |
|
|
||||||
| //! \details | |
|
|
||||||
| //! \~english | Детальное объяснение на английском языке |
|
|
||||||
| //! \~russian | Детальное объяснение на русском языке |
|
|
||||||
| //! \note | |
|
|
||||||
| //! \~english | Важное примечание о сложности/поведении на английском языке |
|
|
||||||
| //! \~russian | Важное примечание о сложности/поведении на русском языке |
|
|
||||||
| //! \~\sa | Ссылки на связанные функции |
|
|
||||||
|
|
||||||
NOTE: Не использовать секции \param и \return
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
# План рефакторинга PIVector2D
|
|
||||||
|
|
||||||
## Этап 1: Сборка
|
|
||||||
|
|
||||||
### 1.1 Собрать проект
|
|
||||||
- [x] собери проект, при необходимости поправь ошибки
|
|
||||||
|
|
||||||
## Этап 2: Проверить и поправить тесты
|
|
||||||
|
|
||||||
### 2.1 Запустить тесты
|
|
||||||
- [x] Запустить: `./build/tests/pip_math_test --gtest_filter="*Vector2D*"`
|
|
||||||
- [x] В случае ошибок внести правки в pivector2d.h
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Этап 3: Заменить PIPair<ssize_t, ssize_t> на PIVector2DIndex
|
|
||||||
|
|
||||||
### 3.1 Создать структуру PIVector2DIndex
|
|
||||||
- [x] Создано: `struct Index { ssize_t row; ssize_t col; };`
|
|
||||||
|
|
||||||
### 3.2 Обновить return types
|
|
||||||
- [x] indexOf() -> возвращает Index вместо PIPair<ssize_t, ssize_t>
|
|
||||||
- [x] lastIndexOf()
|
|
||||||
- [x] indexWhere()
|
|
||||||
- [x] lastIndexWhere()
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
Reference in New Issue
Block a user