From 3e4ea82406f0073f84c77a27ecc7fe9f30e85f2d Mon Sep 17 00:00:00 2001 From: Wojciech Sekta Date: Thu, 11 Jan 2024 22:17:36 +0100 Subject: [PATCH] update documentation --- .gitignore | 4 +- Doxyfile | 10 +- README.md | 4 +- docs/DoxygenLayout.xml | 240 +++++++++++++++++++++++++++++++++++ docs/database.md | 9 ++ docs/main.md | 10 +- docs/model.md | 128 +++++++++++++++++++ docs/query.md | 7 + include/orm-cxx/database.hpp | 12 +- 9 files changed, 408 insertions(+), 16 deletions(-) create mode 100644 docs/DoxygenLayout.xml create mode 100644 docs/database.md create mode 100644 docs/model.md create mode 100644 docs/query.md diff --git a/.gitignore b/.gitignore index 035be92..0fee50a 100644 --- a/.gitignore +++ b/.gitignore @@ -34,4 +34,6 @@ *build*/ .idea/ .vscode/ -vcpkg_installed/ \ No newline at end of file +vcpkg_installed/ +html/ +doxygen-awesome-css \ No newline at end of file diff --git a/Doxyfile b/Doxyfile index 811ea10..791e0fd 100644 --- a/Doxyfile +++ b/Doxyfile @@ -351,7 +351,7 @@ EXTENSION_MAPPING = # case of backward compatibilities issues. # The default value is: YES. -MARKDOWN_SUPPORT = NO +MARKDOWN_SUPPORT = YES # When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up # to that level are automatically included in the table of contents, even if @@ -906,7 +906,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = include/orm-cxx +INPUT = docs/ include/orm-cxx/ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1328,10 +1328,8 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -# HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ -# doxygen-awesome-css/doxygen-awesome-sidebar-only.css \ -# docs/main.css - +HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css \ + doxygen-awesome-css/doxygen-awesome-sidebar-only.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note diff --git a/README.md b/README.md index 6bb68b3..b843e9a 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,9 @@ int main() ## 📖 Documentation -https://wsekta.github.io/orm-cxx/ +## [Markdown](docs/main.md) + +## [Doxygen](https://wsekta.github.io/orm-cxx/) ## Consuming library with CMake (CMake 3.22 or newer) diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml new file mode 100644 index 0000000..94638fc --- /dev/null +++ b/docs/DoxygenLayout.xml @@ -0,0 +1,240 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/database.md b/docs/database.md new file mode 100644 index 0000000..0a3362c --- /dev/null +++ b/docs/database.md @@ -0,0 +1,9 @@ +# Database + +1. [Connect](#connect) +2. [Create table](#create-table) +3. [Delete table](#delete-table) +4. [Insert objects](#insert-objects) +5. [Query objects](#query-objects) + +🚧🚧🚧 TODO 🚧🚧🚧 \ No newline at end of file diff --git a/docs/main.md b/docs/main.md index bd49a42..5d01b33 100644 --- a/docs/main.md +++ b/docs/main.md @@ -1,8 +1,14 @@

ORM C++

ORM Library for Modern C++(C++20) using native reflection.

- + [![clang++](https://github.com/wsekta/orm-cxx/actions/workflows/linux-clang-build.yml/badge.svg?branch=main)](https://github.com/wsekta/orm-cxx/actions/workflows/linux-clang-build.yml?query=branch%3Amain) [![g++](https://github.com/wsekta/orm-cxx/actions/workflows/linux-gxx-build.yml/badge.svg?branch=main)](https://github.com/wsekta/orm-cxx/actions/workflows/linux-gxx-build.yml?query=branch%3Amain) [![msvc](https://github.com/wsekta/orm-cxx/actions/workflows/windows-msvc-build.yml/badge.svg?branch=main)](https://github.com/wsekta/orm-cxx/actions/workflows/windows-msvc-build.yml?query=branch%3Amain) -[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) \ No newline at end of file +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) + +
+ +1. <[Model](model.md)> +2. [Query](query.md) +3. [Database](database.md) \ No newline at end of file diff --git a/docs/model.md b/docs/model.md new file mode 100644 index 0000000..d5376bd --- /dev/null +++ b/docs/model.md @@ -0,0 +1,128 @@ +# Model + +1. [Create simple model](#create-simple-model) +2. [Fields types](#fields-types) +3. [Table name](#table-name) +4. [Mapping fields' names](#mapping-fields-names) +5. [Primary key](#primary-key) + +## Create simple model + +Simple model is a struct with supoorted types of fields. For example: + +```c++ +struct User { + int id; + std::string name; + std::string email; + std::string password; + std::string created_at; + std::string updated_at; +}; +``` + +## Fields types + +Supported types of fields: + +* int +* float +* double +* std::string + +## Table name + +To override table name use `table_name` static field: + +```c++ +struct User { + static constexpr const char* table_name = "users"; + int id; + std::string name; + std::string email; + std::string password; + std::string created_at; + std::string updated_at; +}; +``` + +## Mapping fields' names + +If you want to map fields' names to database columns' names use 'columns_names' static field with dictionary type ( +e.g. `std::map` or `std::unordered_map`). +Not all fields have to be mapped, those that are not mapped will be named the same as fields' names. +For example: + +```c++ +struct User { + static constexpr std::map columns_names = { + {"id", "user_id"}, + {"name", "user_name"}, + {"email", "user_email"}, + {"password", "user_password"}, + {"created_at", "user_created_at"}, + {"updated_at", "user_updated_at"} + }; + int id; + std::string name; + std::string email; + std::string password; + std::string created_at; + std::string updated_at; +}; +``` + +## Primary key + +The default primary key is `id` field: + +```c++ +struct User { + int id; + std::string name; + std::string email; + std::string password; + std::string created_at; + std::string updated_at; +}; +``` + +If you want to change primary key use `id_columns` static field with iterable type containing fields' names as std:: +string (e.g. `std::vector` or `std::array`): + +```c++ +struct User { + static constexpr std::array id_columns = {"id", "name"}; + int id; + std::string name; + std::string email; + std::string password; + std::string created_at; + std::string updated_at; +}; +``` + +You can also create model without primary key, just do not add `id` field: + +```c++ +struct User { + std::string name; + std::string email; + std::string password; + std::string created_at; + std::string updated_at; +}; +``` + +or use `id_columns` static field with empty iterable: + +```c++ +struct User { + static constexpr std::array id_columns = {}; + std::string name; + std::string email; + std::string password; + std::string created_at; + std::string updated_at; +}; +``` \ No newline at end of file diff --git a/docs/query.md b/docs/query.md new file mode 100644 index 0000000..3d566ec --- /dev/null +++ b/docs/query.md @@ -0,0 +1,7 @@ +# Query + +1. [Build query](#build-query) +2. [Limit query](#limit-query) +3. [Offset query](#offset-query) + +🚧🚧🚧 TODO 🚧🚧🚧 \ No newline at end of file diff --git a/include/orm-cxx/database.hpp b/include/orm-cxx/database.hpp index 5582bea..023c850 100644 --- a/include/orm-cxx/database.hpp +++ b/include/orm-cxx/database.hpp @@ -35,8 +35,8 @@ class Database * @brief Executes a query and returns the result. * * @tparam T The type of the query. - * @param query The query to execute. - * @return The result of the query. + * @param query The query of type T to execute. + * @return The vector of objects of type T returned by the query. */ template auto executeQuery(Query& query) -> std::vector @@ -57,7 +57,7 @@ class Database * @brief Executes a insert query for multiple objects. * * @tparam T The type of the query. - * @param query The query to execute. + * @param objects The vector of objects of type T to insert. */ template auto insertObjects(const std::vector& objects) -> void @@ -72,7 +72,7 @@ class Database * @brief Executes a insert query for a single object. * * @tparam T The type of the query. - * @param query The query to execute. + * @param object The object of type T to insert. */ template auto insertObject(T object) -> void @@ -110,7 +110,7 @@ class Database /** * @brief Execute a create table query for a model. * - * @tparam T The type of the model. + * @tparam T The type of the model which table to will be created. */ template auto createTable() -> void @@ -161,7 +161,7 @@ class Database /** * @brief Execute a delete table query for a model. * - * @tparam T The type of the model. + * @tparam T The type of the model which table to will be deleted. */ template auto deleteTable() -> void