From 9347ed2e55d8c0150b77de2b8fb6860fb41b8c21 Mon Sep 17 00:00:00 2001 From: peri4 Date: Fri, 6 May 2022 23:42:20 +0300 Subject: [PATCH] doc --- CMakeLists.txt | 2 +- doc/pages/main.md | 44 +++++++ doc/pages/summary.md | 104 +++++++++++++++ doc/pages/using_basic.md | 128 +++++++++++++++++++ libs/main/core/piincludes.cpp | 234 ---------------------------------- 5 files changed, 277 insertions(+), 235 deletions(-) create mode 100644 doc/pages/main.md create mode 100644 doc/pages/summary.md create mode 100644 doc/pages/using_basic.md diff --git a/CMakeLists.txt b/CMakeLists.txt index 1944b766..df8ff8d1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -579,7 +579,7 @@ if ((NOT PIP_FREERTOS) AND (NOT CROSSTOOLS)) foreach(F ${PIP_MAIN_FOLDERS}) list(APPEND DOXY_INPUT "\"${F}\"") endforeach(F) - string(REPLACE ";" " " DOXY_INPUT "\"${CMAKE_CURRENT_SOURCE_DIR}/libs\"") + string(REPLACE ";" " " DOXY_INPUT "\"${CMAKE_CURRENT_SOURCE_DIR}/libs\";\"${CMAKE_CURRENT_SOURCE_DIR}/doc/pages\"") string(REPLACE ";" " " DOXY_INCLUDE_PATH "${PIP_INCLUDES}") string(REPLACE ";" " " DOXY_DEFINES "${DOXY_DEFINES}") add_documentation(doc doc/Doxyfile.in) diff --git a/doc/pages/main.md b/doc/pages/main.md new file mode 100644 index 00000000..e1ca0a9b --- /dev/null +++ b/doc/pages/main.md @@ -0,0 +1,44 @@ +\~english \mainpage What is PIP +\~russian \mainpage Что такое PIP + + +\~english + +PIP - Platform-Independent Primitives - is crossplatform library for C++ developers. +This library can help developers write non-GUI projects much more quickly, efficiently +and customizable than on pure C++. + +Application written on PIP works the same on any system. One can read and write +any data types, serialize any types to device channels between any systems. + +Many common data types, system primitives and devices implemented in this library. + +PIP also tightly integrates with CMake build system, providing handly search +main library, additional modules of PIP and several utilites. With +CMake with PIP one can easily generate and use code metainformation or +serialize custom types with it versions back-compatability. + +Summary one can find at \ref summary page. + +Basic using of PIP described at \ref using_basic page. + + +\~russian + +PIP - Platform-Independent Primitives - кроссплатформенная библиотека для разработчиков на C++. +Эта библиотека поможет разработчику написать неграфическое приложение быстрее, эффективнее +и более гибко, чем на чистом C++. + +Приложения, написанные на PIP, работают одинаково на многих системах. Можно читать и писать +любые типы данных, сериализовать любые типы в каналы устройств между любыми системами. + +Многие типы данных, системные сущности и устройства реализованы в библиотеке. + +PIP также тесно интегрируется с системой сборки CMake, предоставляя удобный поиск +главной библиотеки, модулей PIP и некоторых утилит. Используя CMake вместе с PIP +можно генерировать и использовать метаинформация о коде или сериализовать +свои типы данных с обратной совместимостью их версий. + +Сводку можно найти на странице \ref summary. + +Базовое использование PIP описано на странице \ref using_basic. diff --git a/doc/pages/summary.md b/doc/pages/summary.md new file mode 100644 index 00000000..174b9775 --- /dev/null +++ b/doc/pages/summary.md @@ -0,0 +1,104 @@ +\~english \page summary Functionality summary +\~russian \page summary Сводка функциональности + +\~english + +* direct output to console (\a PICout) +* containers (\a PIVector, \a PIDeque, \a PIVector2D, \a PIStack, \a PIQueue, \a PIMap, \a PISet) +* byte array (\a PIByteArray) +* serialization (\a PIChunkStream) +* string (\a PIConstChars, \a PIString, \a PIStringList) +* base object (events and handlers) (\a PIObject) +* multithreading + * thread (\a PIThread) + * blocking (\a PIMutex, \a PISpinlock) + * executor (\a PIThreadPoolExecutor) + * blocking dequeue (\a PIBlockingDequeue) +* timer (\a PITimer) +* tiling console (with widgets) (\a PIScreen) + * simple text rows + * scroll bar + * list + * button + * buttons group + * check box + * progress bar + * PICout output + * text input +* I/O devices + * base class (\a PIIODevice) + * file (\a PIFile) + * serial port (\a PISerial) + * ethernet (\a PIEthernet) + * USB (\a PIUSB) + * packets extractor (\a PIPacketExtractor) + * binary log (\a PIBinaryLog) + * complex I/O point (\a PIConnection) + * peering net node (\a PIPeer) + * connection quality diagnotic (\a PIDiagnostics) +* Run-time libraries + * abstract (\a PILibrary) + * plugin (\a PIPluginLoader) +* Mathematics + * complex numbers + * vectors (\a PIMathVector, \a PIMathVectorT) + * matrices (\a PIMathMatrix, \a PIMathMatrixT) + * quaternion (\a PIQuaternion) + * 2D geometry (\a PIPoint, \a PILine, \a PIRect) + * statistic (\a PIStatistic) + * CRC checksum (\a PICRC) + * Fourier transform (\a PIFFTW, \a PIFFT) + * expression evaluator (\a PIEvaluator) +* command-line arguments parser (\a PICLI) +* process (\a PIProcess) + +\~russian + +* общение с консолью (\a PICout) +* контейнеры (\a PIVector, \a PIDeque, \a PIVector2D, \a PIStack, \a PIQueue, \a PIMap, \a PISet) +* байтовый массив (\a PIByteArray) +* сериализация (\a PIChunkStream) +* строка (\a PIConstChars, \a PIString, \a PIStringList) +* базовый объект (события и обработчики) (\a PIObject) +* многопоточность + * поток (\a PIThread) + * блокировки (\a PIMutex, \a PISpinlock) + * исполнитель (\a PIThreadPoolExecutor) + * блокирующая очередь (\a PIBlockingDequeue) +* таймер (\a PITimer) +* тайлинговая консоль (с виджетами) (\a PIScreen) + * простой вывод строк + * скроллбар + * лист + * кнопка + * группа кнопок + * галочка + * прогрессбар + * вывод PICout + * текстовый ввод +* устройства ввода/вывода + * базовый класс (\a PIIODevice) + * файл (\a PIFile) + * последовательный порт (\a PISerial) + * ethernet (\a PIEthernet) + * USB (\a PIUSB) + * packets extractor (\a PIPacketExtractor) + * бинарный логфайл (\a PIBinaryLog) + * сложное составное устройство (\a PIConnection) + * пиринговая сеть (\a PIPeer) + * диагностика качества связи (\a PIDiagnostics) +* поддержка библиотек времени выполнения + * базовая функциональность (\a PILibrary) + * плагин (\a PIPluginLoader) +* Математика + * комплексные числа + * вектора (\a PIMathVector, \a PIMathVectorT) + * матрицы (\a PIMathMatrix, \a PIMathMatrixT) + * кватернион (\a PIQuaternion) + * 2D геометрия (\a PIPoint, \a PILine, \a PIRect) + * статистика (\a PIStatistic) + * CRC контрольная сумма (\a PICRC) + * преобразования Фурье (\a PIFFTW, \a PIFFT) + * вычислитель выражений (\a PIEvaluator) +* парсер аргументов командной строки (\a PICLI) +* процесс (\a PIProcess) diff --git a/doc/pages/using_basic.md b/doc/pages/using_basic.md new file mode 100644 index 00000000..f19f5f5e --- /dev/null +++ b/doc/pages/using_basic.md @@ -0,0 +1,128 @@ +\~english \page using_basic Getting started +\~russian \page using_basic Простые начала + +\~english + +Many novice programmers are solved many common task with system integrity: output to console, +keyboard buttons press detecting, working with serial ports, ethernet or files, and many other. +These tasks can solve this library, and code, based only on PIP will be compile and work +similar on many systems: Windows, any Linux, Red Hat, FreeBSD, MacOS X and QNX. +Typical application on PIP looks like this: \n + +\~russian + +Многие начинающие программисты решают общие задачи взаимодействия с операционной системой: +вывод в консоль, определение нажатия клавиш, работа с последовательными портами, сетью или файлами, +и многое другое. Эти задачи решены в библиотеке, и код, основанный на PIP будет компилироваться +и работать одинаково на многих системах: Windows, любой Linux, Red Hat, FreeBSD, MacOS X и QNX. +Типовое приложение на PIP выглядит примерно так: \n + +\code{.cpp} +#include + + +// declare key press handler +void key_event(char key, void * ); + + +PIConsole console(false, key_event); // don`t start now, key handler is "key_event" + + +// some vars +int i = 2, j = 3; + + +// implicit key press handler +void key_event(char key, void * ) { + switch (key) { + case '-': + i--; + break; + case '+': + i++; + break; + case '(': + j--; + break; + case ')': + j++; + break; + }; +}; + + +class MainClass: public PITimer { + PIOBJECT(MainClass) +public: + MainClass() {} +protected: + void tick(void * data, int delimiter) { + piCout << "timer tick"; + // timer tick + } +}; + + +MainClass main_class; + + +int main(int argc, char * argv[]) { + // enabling auto-detection of exit button press, by default 'Q' (shift+q) + console.enableExitCapture(); + + // if we want to parse command-line arguments + PICLI cli(argc, argv); + cli.addArgument("console"); // "-c" or "--console" + cli.addArgument("debug"); // "-d" or "--debug" + + // enabling or disabling global debug flag + piDebug = cli.hasArgument("debug"); + + // configure console + console.addTab("first tab", '1'); + console.addString("PIP console", 1, PIConsole::Bold); + console.addVariable("int var (i)", &i, 1); + console.addVariable("int green var (j)", &j, 1, PIConsole::Green); + console.addString("'-' - i--", 2); + console.addString("'+' - i++", 2); + console.addString("'(' - j--", 2); + console.addString("')' - j++", 2); + console.addTab("second tab", '2'); + console.addString("col 1", 1); + console.addString("col 2", 2); + console.addString("col 3", 3); + console.setTab("first tab"); + + // start output to console if "console" argument exists + if (cli.hasArgument("console")) + console.start(); + + // start main class, e.g. 40 Hz + main_class.start(25.); + + // wait for 'Q' press, independently if console is started or not + console.waitForFinish(); + + return 0; +}; +\endcode + +\~english + +This code demonstrates simple interactive configurable program, which can be started with console +display or not, and with debug or not. \b MainClass is central class that also can be inherited from +\a PIThread and reimplement \a run() function. +\n Many PIP classes has events and event handlers, which can be connected one to another. +Details you can see at \a PIObject reference page (\ref PIObject_sec0). +\n To configure your program from file use \a PIConfig. +\n If you want more information see \ref using_advanced + +\~russian + +Этот код демонстрирует простую конфигурируемую программу, которая может быть запущена с +This code demonstrates simple interactive configurable program, which can be started with console +display or not, and with debug or not. \b MainClass is central class that also can be inherited from +\a PIThread and reimplement \a run() function. +\n Many PIP classes has events and event handlers, which can be connected one to another. +Details you can see at \a PIObject reference page (\ref PIObject_sec0). +\n To configure your program from file use \a PIConfig. diff --git a/libs/main/core/piincludes.cpp b/libs/main/core/piincludes.cpp index 1a6482b2..9a58445f 100644 --- a/libs/main/core/piincludes.cpp +++ b/libs/main/core/piincludes.cpp @@ -94,237 +94,3 @@ void randomize() { int randomi() { return rand(); } - - -/*! \~english \mainpage What is PIP - * \~russian \mainpage Что такое PIP - * - * \~english - * PIP - Platform-Independent Primitives - is crossplatform library for C++ developers. - * It is wrap around STL and pure C++. This library can help developers write non-GUI - * projects much more quickly, efficiently and customizable than on pure C++. - * Library contains many classes, some of them are pure abstract, some classes - * can be used as they are, some classes should be inherited to new classes. - * PIP provide classes: - * * direct output to console (\a PICout) - * * containers (\a PIVector, \a PIList, \a PIMap, \a PIStack) - * * byte array (\a PIByteArray) - * * string (\a PIString, \a PIStringList) - * * base object (events and handlers) (\a PIObject) - * * multithreading - * * thread (\a PIThread) - * * executor (\a PIThreadPoolExecutor) - * * blocking dequeue (\a PIBlockingDequeue) - * * timer (\a PITimer) - * * tiling console (with widgets) (\a PIScreen) - * * simple text rows - * * scroll bar - * * list - * * button - * * buttons group - * * check box - * * progress bar - * * PICout output - * * text input - * * I/O devices - * * base class (\a PIIODevice) - * * file (\a PIFile) - * * serial port (\a PISerial) - * * ethernet (\a PIEthernet) - * * USB (\a PIUSB) - * * packets extractor (\a PIPacketExtractor) - * * binary log (\a PIBinaryLog) - * * complex I/O point (\a PIConnection) - * * Run-time libraries - * * abstract (\a PILibrary) - * * plugin (\a PIPluginLoader) - * * connection quality diagnotic (\a PIDiagnostics) - * * command-line arguments parser (\a PICLI) - * * math evaluator (\a PIEvaluator) - * * peering net node (\a PIPeer) - * * process (\a PIProcess) - * * state machine (\a PIStateMachine) - * \n \n Basic using of PIP described at page \ref using_basic - * - * \~russian - * PIP - Platform-Independent Primitives - кроссплатформенная библиотека для разработчиков на C++. - * It is wrap around STL and pure C++. This library can help developers write non-GUI - * projects much more quickly, efficiently and customizable than on pure C++. - * PIP предоставляет следующие классы: - * * общение с консолью (\a PICout) - * * контейнеры (\a PIVector, \a PIList, \a PIMap, \a PIStack) - * * байтовый массив (\a PIByteArray) - * * строка (\a PIString, \a PIStringList) - * * базовый объект (события и обработчики) (\a PIObject) - * * многопоточность - * * поток (\a PIThread) - * * исполнитель (\a PIThreadPoolExecutor) - * * блокирующая очередь (\a PIBlockingDequeue) - * * таймер (\a PITimer) - * * тайлинговая консоль (с виджетами) (\a PIScreen) - * * простой вывод строк - * * скроллбар - * * лист - * * кнопка - * * группа кнопок - * * галочка - * * прогрессбар - * * вывод PICout - * * текстовый ввод - * * устройства ввода/вывода - * * базовый класс (\a PIIODevice) - * * файл (\a PIFile) - * * последовательный порт (\a PISerial) - * * ethernet (\a PIEthernet) - * * USB (\a PIUSB) - * * packets extractor (\a PIPacketExtractor) - * * бинарный логфайл (\a PIBinaryLog) - * * сложное составное устройство (\a PIConnection) - * * поддержка библиотек времени выполнения - * * базовая функциональность (\a PILibrary) - * * плагин (\a PIPluginLoader) - * * диагностика качества связи (\a PIDiagnostics) - * * парсер аргументов командной строки (\a PICLI) - * * вычислитель (\a PIEvaluator) - * * пиринговая сеть (\a PIPeer) - * * процесс (\a PIProcess) - * * машина состояний (\a PIStateMachine) - * \n \n Базовое использование PIP описано на странице \ref using_basic - */ - - -/*! \~english \page using_basic Getting started - * \~russian \page using_basic Простые начала - * - * \~english - * Many novice programmers are solved many common task with system integrity: output to console, - * keyboard buttons press detecting, working with serial ports, ethernet or files, and many other. - * These tasks can solve this library, and code, based only on PIP will be compile and work - * similar on many systems: Windows, any Linux, Red Hat, FreeBSD, MacOS X and QNX. - * Typical application on PIP looks like this: \n - * - * \~russian - * Многие начинающие программисты решают общие задачи взаимодействия с операционной системой: - * вывод в консоль, определение нажатия клавиш, работа с последовательными портами, сетью или файлами, - * и многое другое. Эти задачи решены в библиотеке, и код, основанный на PIP будет компилироваться - * и работать одинаково на многих системах: Windows, любой Linux, Red Hat, FreeBSD, MacOS X и QNX. - * Типовое приложение на PIP выглядит примерно так: \n - * -\code{.cpp} -#include - - -// declare key press handler -void key_event(char key, void * ); - - -PIConsole console(false, key_event); // don`t start now, key handler is "key_event" - - -// some vars -int i = 2, j = 3; - - -// implicit key press handler -void key_event(char key, void * ) { - switch (key) { - case '-': - i--; - break; - case '+': - i++; - break; - case '(': - j--; - break; - case ')': - j++; - break; - }; -}; - - -class MainClass: public PITimer { - PIOBJECT(MainClass) -public: - MainClass() {} -protected: - void tick(void * data, int delimiter) { - piCout << "timer tick"; - // timer tick - } -}; - - -MainClass main_class; - - -int main(int argc, char * argv[]) { - // enabling auto-detection of exit button press, by default 'Q' (shift+q) - console.enableExitCapture(); - - // if we want to parse command-line arguments - PICLI cli(argc, argv); - cli.addArgument("console"); // "-c" or "--console" - cli.addArgument("debug"); // "-d" or "--debug" - - // enabling or disabling global debug flag - piDebug = cli.hasArgument("debug"); - - // configure console - console.addTab("first tab", '1'); - console.addString("PIP console", 1, PIConsole::Bold); - console.addVariable("int var (i)", &i, 1); - console.addVariable("int green var (j)", &j, 1, PIConsole::Green); - console.addString("'-' - i--", 2); - console.addString("'+' - i++", 2); - console.addString("'(' - j--", 2); - console.addString("')' - j++", 2); - console.addTab("second tab", '2'); - console.addString("col 1", 1); - console.addString("col 2", 2); - console.addString("col 3", 3); - console.setTab("first tab"); - - // start output to console if "console" argument exists - if (cli.hasArgument("console")) - console.start(); - - // start main class, e.g. 40 Hz - main_class.start(25.); - - // wait for 'Q' press, independently if console is started or not - console.waitForFinish(); - - return 0; -}; -\endcode - * - * \~english - * This code demonstrates simple interactive configurable program, which can be started with console - * display or not, and with debug or not. \b MainClass is central class that also can be inherited from - * \a PIThread and reimplement \a run() function. - * \n Many PIP classes has events and event handlers, which can be connected one to another. - * Details you can see at \a PIObject reference page (\ref PIObject_sec0). - * \n To configure your program from file use \a PIConfig. - * \n If you want more information see \ref using_advanced - * - * \~russian - * Этот код демонстрирует простую конфигурируемую программу, которая может быть запущена с - * This code demonstrates simple interactive configurable program, which can be started with console - * display or not, and with debug or not. \b MainClass is central class that also can be inherited from - * \a PIThread and reimplement \a run() function. - * \n Many PIP classes has events and event handlers, which can be connected one to another. - * Details you can see at \a PIObject reference page (\ref PIObject_sec0). - * \n To configure your program from file use \a PIConfig. - */ - - -/*! \page using_advanced Advanced using - * Sorry, creativity crysis xD - */ - - /* -* \~english -* \~russian -*/