diff --git a/PKGBUILD b/PKGBUILD index 174bab2..5cadc2a 100755 --- a/PKGBUILD +++ b/PKGBUILD @@ -1,7 +1,7 @@ # Maintainer: Matthias Quintern pkgname=gz-cpp-util pkgver=1.3 -pkgrel=0 +pkgrel=1 pkgdesc="Utility library for c++" arch=('any') url="https://github.com/MatthiasQuintern/gz-cpp-util" diff --git a/src/.doxygen_config b/src/.doxygen_config index 45f9020..164a0e3 100755 --- a/src/.doxygen_config +++ b/src/.doxygen_config @@ -32,19 +32,19 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "Glowzwiebel C++ Utility Library" +PROJECT_NAME = "gz-cpp-util" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 1.0 +PROJECT_NUMBER = 1.3 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "A library containing various utilities" +PROJECT_BRIEF = "A c++20 library containing various utilities" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -856,7 +856,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = . container math util ../README.md # .extranous_documentation +INPUT = . container math util ../README.md .extranous_documentation # 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 diff --git a/src/.extranous_documentation.hpp b/src/.extranous_documentation.hpp index ad8ec39..f163014 100644 --- a/src/.extranous_documentation.hpp +++ b/src/.extranous_documentation.hpp @@ -50,4 +50,75 @@ namespace gz { * * */ + + + /** + * @page gen-enum-str Enumeration - String Conversion Script + * @section ges_about About + * gen_enum_str is a python script included in the github repository of this library. + * It generates toString and fromString functions for all enumerations. + * @section ges_how How it works + * The script first searches all enumerations in .hpp files with some regex. + * It only detects them when using this syntax: + * @code + * namespace x::y { + * enum NAME { + * ENUM1, ENUM2=4, ENUM3 = 5, ENUM4, + * }; + * } + * @endcode + * The amount of tabs and spaces are irreleveant, but the { brackets must be on the same line as the declaration. + * Nested namespaces are not supported, you will have to manully edit the generated code if you use them. + * + * After all enumerations were found, it generates toString and fromString declarations in the .hpp file, + * and the declarations in the according .cpp file. It uses two maps type2name and name2type for the conversion. + * The maps are contained in structs, which are declared and defined in the source file. + * + * @section ges_usage Usage + * The script was written for python 3(.10), so you will need to have that installed. + * + * @subsubsection ges_usage_installed With script installed + * Depending on the installation method, it should either be in `/usr/bin` or `/usr/local/bin` which should both be in your `$PATH`. + * Note that it will not have the `.py` ending! + * + * If you do want to run the script on `~/c++/src/myheader.hpp`, you can simply do: + * @code shell + * gen-enum-str ~/c++/src/myheader.hpp + * @endcode + * + * @subsubsection ges_usage_not_installed With script not installed + * If you do want to run the script on `~/c++/src/myheader.hpp`, with the script itself being located at `~/scripts/gen_enum_str.py`, run: + * @code shell + * python3 ~/scripts/gen_enum_str.py ~/c++/src/myheader.hpp + * @endcode + * + * @warning + * This script was tested and should not mess anything up, HOWEVER: + * Do not just run random scripts off the internet on your precious source code without skimming through them first! + * It is also advisable to have up-to-date backups! + * + * To get help, use: + * @code + * gen-enum-str --help + * @endcode + * @code output + * Synposis: get_enum_str.py ... ... + * get_enum_str.py ... -r ... + * -h --help help + * -r recurse: Recurse through given paths process all files. + * -i interactive: prompt for every enumeration + * --no-docs turn off docstring generation + * --docs-no-names do not list names of enumeration values in docstring + * --docs-no-gen do not put "generated by gen_enum_str" in docstring + * --no-throw return empty string/last enum value if the argument for to/fromString is invalid. + * This would normaly throw gz::InvalidArgument + * This option does not make the functions noexcept! + * If the generated code produces errors: + * - check that necessary headers are included in the source file: + * - gz-util/string.hpp + * - gz-util/exceptions.hpp (unless you use --no-throw) + * - check the namespaces of the enumerations, the generated code should be in global namespace + * nested namespace are not supported, you will have to correct that if you use them + * @endcode + */ } diff --git a/src/Makefile b/src/Makefile index 7fa3391..2256eb6 100755 --- a/src/Makefile +++ b/src/Makefile @@ -46,7 +46,7 @@ $(OBJECT_DIRS): install: $(LIB) $(HEADER_INST) @{ [ -z "$(DESTDIR)" ] && echo "Please set the DESTDIR variable (probably to /usr or /usr/local)" && exit 1; } || true install -D -m 755 $< $(DESTDIR)/lib/$(subst ../,,$<) - install -D -m 755 ../gen_enum_str.py $(DESTDIR)/bin/gz-enum-str + install -D -m 755 ../gen_enum_str.py $(DESTDIR)/bin/gen-enum-str uninstall: { [ -z "$(DESTDIR)" ] && echo "Please set the DESTDIR variable (probably to /usr or /usr/local)" && exit 1; } || true