From 7ce99e17913b96785b3cf5537218ca3618200021 Mon Sep 17 00:00:00 2001 From: Daniel Bugl Date: Mon, 14 Sep 2015 14:10:06 +0200 Subject: [PATCH 1/3] improve CODING.md / DESIGN.md formatting --- doc/CODING.md | 102 ++++++++++++++++++++------------------------------ doc/DESIGN.md | 4 +- 2 files changed, 43 insertions(+), 63 deletions(-) diff --git a/doc/CODING.md b/doc/CODING.md index f0d9eb2ad19..c3a10dbabbc 100644 --- a/doc/CODING.md +++ b/doc/CODING.md @@ -11,8 +11,11 @@ After you downloaded and unpacked Elektra you see untypically many folders. The reason is that Elektra project consists of many activities. The most important are: -src ... Here is the source for the library and the tools itself. -tests ... Is the testing framework for the Source + + * **src:** Here is the source for the library and the tools itself. + * **doc:** Documentation for the library. + * **example:** Examples of using the library. + * **tests:** Is the testing framework for the source. ## Source Code ## @@ -23,15 +26,15 @@ The plugins have all kinds of dependencies. It is the responsibility of the plugins to find and check them using CMake. The same guidelines apply for all code in the repository including the plugins. -libloader is responsible for loading the backend modules. It works for -various operating systems by using libltdl, but has an optimized code +`libloader` is responsible for loading the backend modules. It works for +various operating systems by using `libltdl`, but has an optimized code for static linking and win32. kdb is the commandline-tool to access and initialize the Elektra database. ### General Guidelines ### -It is only allowed to break a guidelines if there is a good reason +It is only allowed to break a guideline if there is a good reason for it. When doing so, document the fact either in the commit message, or as comment next to the code. @@ -46,79 +49,57 @@ TODO marker to make the places visible. If you see inconsistency do not hesitate to talk about it with the intent to add a new rule here. -See DESIGN document too, they complement each other. +See [DESIGN](DESIGN.md) document too, they complement each other. ### C Guidelines ### -Functions should not exceed 100 lines. -Files should not exceed 1000 lines. -A line should not be longer then 72 characters. -Split up when those limits are reached. -Rationale: Readability with split windows. - - -The compiler shall not emit any warning (or error). - -Use tabs for indentation. - -Prefer to use blocks to single line statements. - -Curly braces go on a line on their own on the previous indentation level - -Use goto only for error situations. - -Use camelCase for functions and variables. - -Start types with upper-case, everything else with lower-case. - -Avoid spaces between words and round braces. - -Use C-comments /**/ with doxygen style for functions. - -Use C++-comments // for single line statements about the code in the + * Functions should not exceed 100 lines. + * Files should not exceed 1000 lines. + * A line should not be longer then 72 characters. + * Split up when those limits are reached. + * Rationale: Readability with split windows. + * The compiler shall not emit any warning (or error). + * Use tabs for indentation. + * Prefer to use blocks to single line statements. + * Curly braces go on a line on their own on the previous indentation level + * Use goto only for error situations. + * Use camelCase for functions and variables. + * Start types with upper-case, everything else with lower-case. + * Avoid spaces between words and round braces. + * Use C-comments `/**/` with doxygen style for functions. + * Use C++-comments `//` for single line statements about the code in the next line. - -Avoid multiple variable declarations at one place and * are next to the + * Avoid multiple variable declarations at one place and `*` are next to the variable names. + * Use `const` as much as possible. + * Use `static` methods if they should not be externally visible. + * Declare Variables as late as possible, preferable within blocks. + * C-Files have extension `.c`, Header files `.h`. + * Prefix names with `elektra` for internal usage. External API either starts +with `ks`, `key` or `kdb`. -Use const as much as possible. - -Use static methods if they should not be externally visible. - -Declare Variables as late as possible, preferable within blocks. - -C-Files have extension .c, Header files .h. - -Prefix names with elektra for internal usage. External API either starts -with ks, key or kdb. - -Example: src/libelektra/kdb.c +**Example:** [src/libelektra/kdb.c](../src/libelektra/kdb.c) ### C++ Guidelines ### -Everything as in C if not noted otherwise. + * Everything as in C if not noted otherwise. + * Do not use goto at all, use RAII instead. + * Do not use raw pointers, use smart pointers instead. + * C++-Files have extension `.cpp`, Header files `.hpp`. + * Do not use `static`, but anonymous namespaces. + * Write everything within namespaces and do not prefix names. -Do not use goto at all, use RAII instead. - -Do not use raw pointers, use smart pointers instead. - -C++-Files have extension .cpp, Header files .hpp. - -Do not use static, but anonymous namespaces. - -Write everything within namespaces and do not prefix names. - -Example: bindings/cpp/include/kdb.hpp +**Example:** [src/bindings/cpp/include/kdb.hpp](../src/bindings/cpp/include/kdb.hpp) ### Doxygen Guidelines ### -Use doxygen to document APIs, if available. +Use `doxygen` to document APIs, if available. Do not duplicate information available in git in doxygen. -Use \copydoc, \copybrief and \copydetails intensively. +Use `\copydoc`, `\copybrief` and `\copydetails` intensively. Files should start with: @@ -138,4 +119,3 @@ Note: The duplication of the filename, author and date is not needed, because this information is tracked using git. - diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 8dcc9166751..517988b54d6 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -120,7 +120,7 @@ Use the appendant Get functions, to be not depend on that internal facts. const void *keyValue(const Key *key); does not specify whether it is a binary or string, it will just return -the pointer to it. When Key is a string (check with keyIsString()) at +the pointer to it. When Key is a string (check with `keyIsString()`) at least "" will be returned, see below Return Values for strings. For binary data a NULL pointer is also possible to distinguish between no data and '\0'. @@ -175,7 +175,7 @@ There are some functions which return an internal string: const char *keyOwner(const Key *key); const char *keyComment(const Key *key); -and in the case that (keyIsBinary(key)==1) also: +and in the case that (`keyIsBinary(key)==1`) also: const void *keyValue(const Key *key); From 3ada67ca5db7ee592eac404243172299c6151733 Mon Sep 17 00:00:00 2001 From: Daniel Bugl Date: Mon, 14 Sep 2015 14:32:56 +0200 Subject: [PATCH 2/3] README.md: use SVG logo (transparent background) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 30afccfccc9..0aa6a310850 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ _Elektra provides a universal and secure framework to store configuration parameters in a global, hierarchical key database._ -![Elektra](doc/images/circle.jpg) +Elektra The core is a small library implemented in C. The plugin-based framework fulfills many configuration-related tasks to avoid any unnecessary code duplication From adea7003158e984221cf4977ef7dc82d08fc0c7c Mon Sep 17 00:00:00 2001 From: Daniel Bugl Date: Mon, 14 Sep 2015 14:40:28 +0200 Subject: [PATCH 3/3] README.md: add envvar example --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0aa6a310850..d8556fa7b3e 100644 --- a/README.md +++ b/README.md @@ -55,10 +55,19 @@ kdb qt-gui Or you can use the `kdb` command to configure your applications: ```bash -kdb set user/test "something" -kdb get user/test +kdb set user/env/override/HTTP_PROXY "http://my.proxy:8080" ``` +This will set the `HTTP_PROXY` environment variable to `http://my.proxy:8080`. +Configuration can be retrieved with `kdb get`: + +```bash +kdb get user/env/override/HTTP_PROXY +``` + +For more information about environment variables and elektra, see +[src/libgetenv/README.md](src/libgetenv/README.md) + ## Goals ##