From 12c065a27193782737c4811ae4e9e0814da86330 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Sun, 3 Jan 2021 16:29:05 +0100 Subject: [PATCH 01/29] doc: fix format of DESIGN.md --- doc/DESIGN.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index fd3eb3bd34d..13986d9b486 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -283,3 +283,107 @@ const Key *keyGetMeta(const Key *key, const char* metaName); The reason behind this is, that the above functions – as their name suggest – only retrieve values. The returned value must not be modified directly. + +## Design Guidelines Checklist + +On potential changes of the API/ABI as detected by +[`elektra-icheck`](https://build.libelektra.org/job/elektra-icheck), +please make sure the API has been reviewed according to the +following 2 checklists: + +## Checklist for overall API + +### Naming + +- [ ] Inconsistent naming of functions or variables + +### Consistency + +- [ ] Consistent naming schemes +- [ ] Similar things are named similarly +- [ ] Different things are named differently +- [ ] The order of arguments should be consistent across similar functions +- [ ] Code is formatted according to the [style guidelines](/doc/CODING.md#coding-style) + +### Structural Clarity + +- [ ] Functions with similar functionality are grouped into the same namespace + +### Compatibility + +- [ ] All Bindings have been updated to reflect the new API and work properly + +### Extensibility + +- [ ] New API is easily extensible with additional functionality +- [ ] Components do not depend too heavily on each other + +## Checklist for each function + +### Documentation + +- [ ] Doxygen Documentation is complete + (covers all parameters, brief/short summary, examples) +- [ ] Change is mentioned in the release notes +- [ ] Inconsistencies between documentation and code +- [ ] Inconsistencies between documentation and tests +- [ ] Proper Documentation of all side effects +- [ ] Proper Documentation of thread-safety of function +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes + +### Naming + +- [ ] Abbreviations should be avoided in function / parameter names +- [ ] Function / parameter names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous + +### Compatibility + +- [ ] ABI/API forward-compatible (breaking backwards-compatibility + to add new symbols is fine) +- [ ] #ifdef present for experimental features + +### Parameter & Return Types + +- [ ] Returning a not specific enough type +- [ ] Requiring a not liberal enough parameter +- [ ] should not have multiple parameters of the same type +- [ ] Functions should use Constant Types instead of Boolean Types wherever + sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Functions should not have a long list of parameters (>8) + +### Error Handling + +- [ ] When an error occurs, a clear error message should be provided +- [ ] Errors of the same type should emit the same error message +- [ ] The error message informs the user of possible causes for the problem +- [ ] All possible error messages are documented +- [ ] All possible errors states lead to an error +- [ ] Proper error codes are chosen + +### Structural Clarity + +- [ ] Function does exactly one thing +- [ ] Function should have no side effects + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Functions should not cause memory-leaks +- [ ] Every Buffer should be accompanied by a max size limit +- [ ] Functions who require a large amount of memory to be allocated, + state so in their documentation + +### Extensibility + +- [ ] Function is easily extensible with additional functionality + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] Tests cover edge-cases +- [ ] Tests cover error-cases and check for proper error messages +- [ ] Inconsistencies between tests and code +- [ ] Inconsistencies between tests and documentation From 9a76270e79837b3d5e0b96fc140b8e5e0dca66b4 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Sun, 3 Jan 2021 18:32:31 +0100 Subject: [PATCH 02/29] doc: Apply suggestions from @markus2330 code review Co-authored-by: markus2330 --- doc/DESIGN.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 13986d9b486..bde36050884 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -324,7 +324,7 @@ following 2 checklists: - [ ] Doxygen Documentation is complete (covers all parameters, brief/short summary, examples) -- [ ] Change is mentioned in the release notes +- [ ] Change is mentioned in the Compatibility section of the release notes - [ ] Inconsistencies between documentation and code - [ ] Inconsistencies between documentation and tests - [ ] Proper Documentation of all side effects @@ -348,8 +348,8 @@ following 2 checklists: - [ ] Returning a not specific enough type - [ ] Requiring a not liberal enough parameter -- [ ] should not have multiple parameters of the same type -- [ ] Functions should use Constant Types instead of Boolean Types wherever +- [ ] Should not have multiple parameters of the same type +- [ ] Functions should use constant types instead of boolean types sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Functions should not have a long list of parameters (>8) From ae330162515a477836804b734272df2040f47753 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Sun, 3 Jan 2021 23:20:09 +0100 Subject: [PATCH 03/29] doc: Further improve guidelines in DESIGN.md --- doc/DESIGN.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index bde36050884..911f5ee2ba7 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -293,13 +293,9 @@ following 2 checklists: ## Checklist for overall API -### Naming - -- [ ] Inconsistent naming of functions or variables - ### Consistency -- [ ] Consistent naming schemes +- [ ] Consistent naming schemes for enums, macros, typedefs and functions - [ ] Similar things are named similarly - [ ] Different things are named differently - [ ] The order of arguments should be consistent across similar functions @@ -320,18 +316,23 @@ following 2 checklists: ## Checklist for each function + ### Documentation -- [ ] Doxygen Documentation is complete - (covers all parameters, brief/short summary, examples) - [ ] Change is mentioned in the Compatibility section of the release notes - [ ] Inconsistencies between documentation and code - [ ] Inconsistencies between documentation and tests -- [ ] Proper Documentation of all side effects - [ ] Proper Documentation of thread-safety of function - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes +#### Doxygen + +- [ ] Return Value +- [ ] Precondition / Postcondition / Invariant +- [ ] `@see` +- [ ] `@since` + ### Naming - [ ] Abbreviations should be avoided in function / parameter names @@ -342,7 +343,6 @@ following 2 checklists: - [ ] ABI/API forward-compatible (breaking backwards-compatibility to add new symbols is fine) -- [ ] #ifdef present for experimental features ### Parameter & Return Types @@ -352,27 +352,25 @@ following 2 checklists: - [ ] Functions should use constant types instead of boolean types sensible - [ ] Wherever possible, function parameters should be `const` -- [ ] Functions should not have a long list of parameters (>8) ### Error Handling - [ ] When an error occurs, a clear error message should be provided - [ ] Errors of the same type should emit the same error message - [ ] The error message informs the user of possible causes for the problem -- [ ] All possible error messages are documented +- [ ] All possible error categories are documented - [ ] All possible errors states lead to an error - [ ] Proper error codes are chosen ### Structural Clarity -- [ ] Function does exactly one thing +- [ ] Function should do exactly one thing - [ ] Function should have no side effects ### Memory Management - [ ] Memory Management should be handled by the function wherever possible - [ ] Functions should not cause memory-leaks -- [ ] Every Buffer should be accompanied by a max size limit - [ ] Functions who require a large amount of memory to be allocated, state so in their documentation @@ -384,6 +382,6 @@ following 2 checklists: - [ ] Added functions are fully covered by tests - [ ] Tests cover edge-cases -- [ ] Tests cover error-cases and check for proper error messages +- [ ] Tests cover all categories of errors - [ ] Inconsistencies between tests and code - [ ] Inconsistencies between tests and documentation From 78bf45f48080f0fe30aca6a17aca9e7d458d7dea Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Mon, 4 Jan 2021 19:14:14 +0100 Subject: [PATCH 04/29] doc: further refine Design-Guidelines --- doc/DESIGN.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 911f5ee2ba7..80b454607a2 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -291,6 +291,7 @@ On potential changes of the API/ABI as detected by please make sure the API has been reviewed according to the following 2 checklists: + ## Checklist for overall API ### Consistency @@ -299,11 +300,10 @@ following 2 checklists: - [ ] Similar things are named similarly - [ ] Different things are named differently - [ ] The order of arguments should be consistent across similar functions -- [ ] Code is formatted according to the [style guidelines](/doc/CODING.md#coding-style) ### Structural Clarity -- [ ] Functions with similar functionality are grouped into the same namespace +- [ ] Functions with similar functionality have the same prefix ### Compatibility @@ -314,8 +314,8 @@ following 2 checklists: - [ ] New API is easily extensible with additional functionality - [ ] Components do not depend too heavily on each other -## Checklist for each function +## Checklist for each function ### Documentation @@ -323,8 +323,6 @@ following 2 checklists: - [ ] Inconsistencies between documentation and code - [ ] Inconsistencies between documentation and tests - [ ] Proper Documentation of thread-safety of function -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes #### Doxygen @@ -341,17 +339,20 @@ following 2 checklists: ### Compatibility +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes - [ ] ABI/API forward-compatible (breaking backwards-compatibility to add new symbols is fine) ### Parameter & Return Types -- [ ] Returning a not specific enough type -- [ ] Requiring a not liberal enough parameter -- [ ] Should not have multiple parameters of the same type +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most liberal type possible +- [ ] Functions should not have multiple parameters of the same type - [ ] Functions should use constant types instead of boolean types sensible - [ ] Wherever possible, function parameters should be `const` +- [ ] Functions should have the least amount of parameters feasible ### Error Handling From a84a97952e2b2ed9ff39121f0f46b36b3d6b4067 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Mon, 1 Feb 2021 16:10:43 +0100 Subject: [PATCH 05/29] further improve checklist --- doc/DESIGN.md | 47 +++++++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 80b454607a2..e4e2bc121a5 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -320,9 +320,11 @@ following 2 checklists: ### Documentation - [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Inconsistencies between documentation and code -- [ ] Inconsistencies between documentation and tests +- [ ] No inconsistencies between documentation and code +- [ ] No inconsistencies between documentation and tests - [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented #### Doxygen @@ -330,59 +332,56 @@ following 2 checklists: - [ ] Precondition / Postcondition / Invariant - [ ] `@see` - [ ] `@since` +- [ ] `@ingroup` ### Naming -- [ ] Abbreviations should be avoided in function / parameter names -- [ ] Function / parameter names should neither be too long, nor too short +- [ ] Abbreviations should be avoided in function names +- [ ] Abbreviations should be avoided in parameter names +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous ### Compatibility - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API forward-compatible (breaking backwards-compatibility - to add new symbols is fine) +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) ### Parameter & Return Types - [ ] Functions should return the most specific type possible - [ ] Functions should require the most liberal type possible -- [ ] Functions should not have multiple parameters of the same type - [ ] Functions should use constant types instead of boolean types - sensible + wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Functions should have the least amount of parameters feasible -### Error Handling - -- [ ] When an error occurs, a clear error message should be provided -- [ ] Errors of the same type should emit the same error message -- [ ] The error message informs the user of possible causes for the problem -- [ ] All possible error categories are documented -- [ ] All possible errors states lead to an error -- [ ] Proper error codes are chosen - ### Structural Clarity - [ ] Function should do exactly one thing - [ ] Function should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Functions should not cause memory-leaks -- [ ] Functions who require a large amount of memory to be allocated, +- [ ] Functions, who require a large amount of memory to be allocated, state so in their documentation ### Extensibility -- [ ] Function is easily extensible with additional functionality +- [ ] Function is easily extensible with additional functionality via bitmap-flags +- [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests -- [ ] Tests cover edge-cases -- [ ] Tests cover all categories of errors -- [ ] Inconsistencies between tests and code -- [ ] Inconsistencies between tests and documentation +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Tests cover possible edge-cases +- [ ] No inconsistencies between tests and code +- [ ] No inconsistencies between tests and documentation From 6b5cc7563536dd87b8b13d823875a028a9479fd6 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 2 Feb 2021 20:56:54 +0100 Subject: [PATCH 06/29] Apply suggestions from code review Co-authored-by: markus2330 --- doc/DESIGN.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index e4e2bc121a5..44095aed380 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -296,7 +296,7 @@ following 2 checklists: ### Consistency -- [ ] Consistent naming schemes for enums, macros, typedefs and functions +- [ ] Consistent naming schemes for enums, macros, typedefs and functions (called components below) - [ ] Similar things are named similarly - [ ] Different things are named differently - [ ] The order of arguments should be consistent across similar functions @@ -307,12 +307,12 @@ following 2 checklists: ### Compatibility -- [ ] All Bindings have been updated to reflect the new API and work properly +- [ ] All bindings have been updated to reflect the new API and work properly ### Extensibility - [ ] New API is easily extensible with additional functionality -- [ ] Components do not depend too heavily on each other +- [ ] Components only depend on each other if needed ## Checklist for each function @@ -333,6 +333,7 @@ following 2 checklists: - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function ### Naming @@ -361,8 +362,8 @@ following 2 checklists: ### Structural Clarity -- [ ] Function should do exactly one thing -- [ ] Function should have no side effects +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects - [ ] Configuration options are named constants - [ ] Function belongs to appropriate group From dd963c6faf231afff1ddf498e43bc81fb71dfb85 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 2 Feb 2021 21:16:25 +0100 Subject: [PATCH 07/29] doc: incorporate suggestions from @markus2330 --- doc/DESIGN.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 44095aed380..c0a107f2a2d 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -296,8 +296,8 @@ following 2 checklists: ### Consistency -- [ ] Consistent naming schemes for enums, macros, typedefs and functions (called components below) -- [ ] Similar things are named similarly +- [ ] Consistent naming schemes for enums, macros, typedefs and functions +- [ ] Same things are named the same and included in [Glossary](/doc/help/elektra-glossary.md) - [ ] Different things are named differently - [ ] The order of arguments should be consistent across similar functions @@ -320,7 +320,6 @@ following 2 checklists: ### Documentation - [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and code - [ ] No inconsistencies between documentation and tests - [ ] Proper Documentation of thread-safety of function - [ ] All possible error states are documented @@ -328,8 +327,8 @@ following 2 checklists: #### Doxygen -- [ ] Return Value - [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` @@ -337,8 +336,10 @@ following 2 checklists: ### Naming -- [ ] Abbreviations should be avoided in function names -- [ ] Abbreviations should be avoided in parameter names +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) - [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous @@ -354,10 +355,11 @@ following 2 checklists: ### Parameter & Return Types - [ ] Functions should return the most specific type possible -- [ ] Functions should require the most liberal type possible +- [ ] Functions should require the most general type possible - [ ] Functions should use constant types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` - [ ] Functions should have the least amount of parameters feasible ### Structural Clarity @@ -370,12 +372,11 @@ following 2 checklists: ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Functions, who require a large amount of memory to be allocated, - state so in their documentation +- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with additional functionality via bitmap-flags +- [ ] Function is easily extensible with function flags (constants) - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests @@ -383,6 +384,5 @@ following 2 checklists: - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible configuration options are covered by tests -- [ ] Tests cover possible edge-cases -- [ ] No inconsistencies between tests and code +- [ ] Function body has full test coverage - [ ] No inconsistencies between tests and documentation From 09859728a898596ee978cfe91627d32270fc4db0 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 9 Feb 2021 19:37:08 +0100 Subject: [PATCH 08/29] docs: add script for generating review files - add generated review files to docs --- doc/api_review/README.md | 25 ++++++ doc/api_review/core/kdbClose.md | 79 ++++++++++++++++++ doc/api_review/core/kdbEnsure.md | 79 ++++++++++++++++++ doc/api_review/core/kdbGet.md | 79 ++++++++++++++++++ doc/api_review/core/kdbOpen.md | 79 ++++++++++++++++++ doc/api_review/core/kdbSet.md | 79 ++++++++++++++++++ doc/api_review/core/keyAddBaseName.md | 79 ++++++++++++++++++ doc/api_review/core/keyAddName.md | 79 ++++++++++++++++++ doc/api_review/core/keyBaseName.md | 79 ++++++++++++++++++ doc/api_review/core/keyClear.md | 79 ++++++++++++++++++ doc/api_review/core/keyCmp.md | 79 ++++++++++++++++++ doc/api_review/core/keyCopy.md | 79 ++++++++++++++++++ doc/api_review/core/keyCopyAllMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keyCopyMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keyCurrentMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keyDecRef.md | 79 ++++++++++++++++++ doc/api_review/core/keyDel.md | 79 ++++++++++++++++++ doc/api_review/core/keyDup.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetBaseName.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetBaseNameSize.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetBinary.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetName.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetNameSize.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetNamespace.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetRef.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetString.md | 79 ++++++++++++++++++ .../core/keyGetUnescapedNameSize.md | 79 ++++++++++++++++++ doc/api_review/core/keyGetValueSize.md | 79 ++++++++++++++++++ doc/api_review/core/keyIncRef.md | 79 ++++++++++++++++++ doc/api_review/core/keyIsBelow.md | 79 ++++++++++++++++++ doc/api_review/core/keyIsBelowOrSame.md | 79 ++++++++++++++++++ doc/api_review/core/keyIsBinary.md | 79 ++++++++++++++++++ doc/api_review/core/keyIsDirectlyBelow.md | 79 ++++++++++++++++++ doc/api_review/core/keyIsLocked.md | 79 ++++++++++++++++++ doc/api_review/core/keyIsString.md | 79 ++++++++++++++++++ doc/api_review/core/keyLock.md | 79 ++++++++++++++++++ doc/api_review/core/keyMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keyName.md | 79 ++++++++++++++++++ doc/api_review/core/keyNeedSync.md | 79 ++++++++++++++++++ doc/api_review/core/keyNew.md | 79 ++++++++++++++++++ doc/api_review/core/keyNextMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keyRewindMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keySetBaseName.md | 79 ++++++++++++++++++ doc/api_review/core/keySetBinary.md | 79 ++++++++++++++++++ doc/api_review/core/keySetMeta.md | 79 ++++++++++++++++++ doc/api_review/core/keySetName.md | 79 ++++++++++++++++++ doc/api_review/core/keySetNamespace.md | 79 ++++++++++++++++++ doc/api_review/core/keySetString.md | 79 ++++++++++++++++++ doc/api_review/core/keyString.md | 79 ++++++++++++++++++ doc/api_review/core/keyUnescapedName.md | 79 ++++++++++++++++++ doc/api_review/core/keyVNew.md | 79 ++++++++++++++++++ doc/api_review/core/keyValue.md | 79 ++++++++++++++++++ doc/api_review/core/ksAppend.md | 79 ++++++++++++++++++ doc/api_review/core/ksAppendKey.md | 79 ++++++++++++++++++ doc/api_review/core/ksAtCursor.md | 79 ++++++++++++++++++ doc/api_review/core/ksClear.md | 79 ++++++++++++++++++ doc/api_review/core/ksCopy.md | 79 ++++++++++++++++++ doc/api_review/core/ksCurrent.md | 79 ++++++++++++++++++ doc/api_review/core/ksCut.md | 79 ++++++++++++++++++ doc/api_review/core/ksDel.md | 79 ++++++++++++++++++ doc/api_review/core/ksDup.md | 79 ++++++++++++++++++ doc/api_review/core/ksGetCursor.md | 79 ++++++++++++++++++ doc/api_review/core/ksGetSize.md | 79 ++++++++++++++++++ doc/api_review/core/ksHead.md | 79 ++++++++++++++++++ doc/api_review/core/ksLookup.md | 79 ++++++++++++++++++ doc/api_review/core/ksLookupByName.md | 79 ++++++++++++++++++ doc/api_review/core/ksNeedSync.md | 79 ++++++++++++++++++ doc/api_review/core/ksNew.md | 79 ++++++++++++++++++ doc/api_review/core/ksNext.md | 79 ++++++++++++++++++ doc/api_review/core/ksPop.md | 79 ++++++++++++++++++ doc/api_review/core/ksRewind.md | 79 ++++++++++++++++++ doc/api_review/core/ksSetCursor.md | 79 ++++++++++++++++++ doc/api_review/core/ksTail.md | 79 ++++++++++++++++++ doc/api_review/core/ksVNew.md | 79 ++++++++++++++++++ scripts/api_review/.gitignore | 1 + scripts/api_review/README.md | 2 + scripts/api_review/generate_review_files.py | 82 +++++++++++++++++++ scripts/api_review/methods.txt | 74 +++++++++++++++++ scripts/api_review/template.md | 79 ++++++++++++++++++ 80 files changed, 6109 insertions(+) create mode 100644 doc/api_review/README.md create mode 100644 doc/api_review/core/kdbClose.md create mode 100644 doc/api_review/core/kdbEnsure.md create mode 100644 doc/api_review/core/kdbGet.md create mode 100644 doc/api_review/core/kdbOpen.md create mode 100644 doc/api_review/core/kdbSet.md create mode 100644 doc/api_review/core/keyAddBaseName.md create mode 100644 doc/api_review/core/keyAddName.md create mode 100644 doc/api_review/core/keyBaseName.md create mode 100644 doc/api_review/core/keyClear.md create mode 100644 doc/api_review/core/keyCmp.md create mode 100644 doc/api_review/core/keyCopy.md create mode 100644 doc/api_review/core/keyCopyAllMeta.md create mode 100644 doc/api_review/core/keyCopyMeta.md create mode 100644 doc/api_review/core/keyCurrentMeta.md create mode 100644 doc/api_review/core/keyDecRef.md create mode 100644 doc/api_review/core/keyDel.md create mode 100644 doc/api_review/core/keyDup.md create mode 100644 doc/api_review/core/keyGetBaseName.md create mode 100644 doc/api_review/core/keyGetBaseNameSize.md create mode 100644 doc/api_review/core/keyGetBinary.md create mode 100644 doc/api_review/core/keyGetMeta.md create mode 100644 doc/api_review/core/keyGetName.md create mode 100644 doc/api_review/core/keyGetNameSize.md create mode 100644 doc/api_review/core/keyGetNamespace.md create mode 100644 doc/api_review/core/keyGetRef.md create mode 100644 doc/api_review/core/keyGetString.md create mode 100644 doc/api_review/core/keyGetUnescapedNameSize.md create mode 100644 doc/api_review/core/keyGetValueSize.md create mode 100644 doc/api_review/core/keyIncRef.md create mode 100644 doc/api_review/core/keyIsBelow.md create mode 100644 doc/api_review/core/keyIsBelowOrSame.md create mode 100644 doc/api_review/core/keyIsBinary.md create mode 100644 doc/api_review/core/keyIsDirectlyBelow.md create mode 100644 doc/api_review/core/keyIsLocked.md create mode 100644 doc/api_review/core/keyIsString.md create mode 100644 doc/api_review/core/keyLock.md create mode 100644 doc/api_review/core/keyMeta.md create mode 100644 doc/api_review/core/keyName.md create mode 100644 doc/api_review/core/keyNeedSync.md create mode 100644 doc/api_review/core/keyNew.md create mode 100644 doc/api_review/core/keyNextMeta.md create mode 100644 doc/api_review/core/keyRewindMeta.md create mode 100644 doc/api_review/core/keySetBaseName.md create mode 100644 doc/api_review/core/keySetBinary.md create mode 100644 doc/api_review/core/keySetMeta.md create mode 100644 doc/api_review/core/keySetName.md create mode 100644 doc/api_review/core/keySetNamespace.md create mode 100644 doc/api_review/core/keySetString.md create mode 100644 doc/api_review/core/keyString.md create mode 100644 doc/api_review/core/keyUnescapedName.md create mode 100644 doc/api_review/core/keyVNew.md create mode 100644 doc/api_review/core/keyValue.md create mode 100644 doc/api_review/core/ksAppend.md create mode 100644 doc/api_review/core/ksAppendKey.md create mode 100644 doc/api_review/core/ksAtCursor.md create mode 100644 doc/api_review/core/ksClear.md create mode 100644 doc/api_review/core/ksCopy.md create mode 100644 doc/api_review/core/ksCurrent.md create mode 100644 doc/api_review/core/ksCut.md create mode 100644 doc/api_review/core/ksDel.md create mode 100644 doc/api_review/core/ksDup.md create mode 100644 doc/api_review/core/ksGetCursor.md create mode 100644 doc/api_review/core/ksGetSize.md create mode 100644 doc/api_review/core/ksHead.md create mode 100644 doc/api_review/core/ksLookup.md create mode 100644 doc/api_review/core/ksLookupByName.md create mode 100644 doc/api_review/core/ksNeedSync.md create mode 100644 doc/api_review/core/ksNew.md create mode 100644 doc/api_review/core/ksNext.md create mode 100644 doc/api_review/core/ksPop.md create mode 100644 doc/api_review/core/ksRewind.md create mode 100644 doc/api_review/core/ksSetCursor.md create mode 100644 doc/api_review/core/ksTail.md create mode 100644 doc/api_review/core/ksVNew.md create mode 100644 scripts/api_review/.gitignore create mode 100644 scripts/api_review/README.md create mode 100644 scripts/api_review/generate_review_files.py create mode 100644 scripts/api_review/methods.txt create mode 100644 scripts/api_review/template.md diff --git a/doc/api_review/README.md b/doc/api_review/README.md new file mode 100644 index 00000000000..b3823636db7 --- /dev/null +++ b/doc/api_review/README.md @@ -0,0 +1,25 @@ +# Elektra API Review +This folder contains all API design reviews conducted on the Elektra library. +Below you can find a short description of the review process. + +## Review Process +This review is performed for each function separately. Each function should be +evaluated according to the checklist. The reviewer judges for every bullet +point, whether the function does / does not fulfill the bullet point. For +every unfulfilled point a short explanation has to be given why the reviewer +thinks the function does not fulfill the respective bullet point. This is done +simply by providing a short description of the issue below the respective +bullet point. After the review has been completed, the reviewer creates an +issue for every unfulfilled bullet point so it can be fixed by the Elektra team. + +## Checklist Legend + +- [ ] not fulfilled + This is the reason for why its is not fulfilled +- [x] fulfilled +- not applicable + + +## Templates +The template and the script for generating review files based on that template +can be found [here](/scripts/api_review/README.md) \ No newline at end of file diff --git a/doc/api_review/core/kdbClose.md b/doc/api_review/core/kdbClose.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/kdbClose.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/kdbEnsure.md b/doc/api_review/core/kdbEnsure.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/kdbEnsure.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/kdbGet.md b/doc/api_review/core/kdbGet.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/kdbGet.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/kdbOpen.md b/doc/api_review/core/kdbOpen.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/kdbOpen.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/kdbSet.md b/doc/api_review/core/kdbSet.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/kdbSet.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyAddBaseName.md b/doc/api_review/core/keyAddBaseName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyAddBaseName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyAddName.md b/doc/api_review/core/keyAddName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyAddName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyBaseName.md b/doc/api_review/core/keyBaseName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyBaseName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyClear.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyCmp.md b/doc/api_review/core/keyCmp.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyCmp.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyCopy.md b/doc/api_review/core/keyCopy.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyCopy.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyCopyAllMeta.md b/doc/api_review/core/keyCopyAllMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyCopyAllMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyCopyMeta.md b/doc/api_review/core/keyCopyMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyCopyMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyCurrentMeta.md b/doc/api_review/core/keyCurrentMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyCurrentMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyDecRef.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyDel.md b/doc/api_review/core/keyDel.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyDel.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyDup.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetBaseName.md b/doc/api_review/core/keyGetBaseName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetBaseName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetBaseNameSize.md b/doc/api_review/core/keyGetBaseNameSize.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetBaseNameSize.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetBinary.md b/doc/api_review/core/keyGetBinary.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetBinary.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetMeta.md b/doc/api_review/core/keyGetMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetNameSize.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetNamespace.md b/doc/api_review/core/keyGetNamespace.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetNamespace.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetRef.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetString.md b/doc/api_review/core/keyGetString.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetString.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetUnescapedNameSize.md b/doc/api_review/core/keyGetUnescapedNameSize.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetUnescapedNameSize.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyGetValueSize.md b/doc/api_review/core/keyGetValueSize.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyGetValueSize.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyIncRef.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyIsBelow.md b/doc/api_review/core/keyIsBelow.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyIsBelow.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyIsBelowOrSame.md b/doc/api_review/core/keyIsBelowOrSame.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyIsBelowOrSame.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyIsBinary.md b/doc/api_review/core/keyIsBinary.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyIsBinary.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyIsDirectlyBelow.md b/doc/api_review/core/keyIsDirectlyBelow.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyIsDirectlyBelow.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyIsLocked.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyIsString.md b/doc/api_review/core/keyIsString.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyIsString.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyLock.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyMeta.md b/doc/api_review/core/keyMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyName.md b/doc/api_review/core/keyName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyNeedSync.md b/doc/api_review/core/keyNeedSync.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyNeedSync.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyNew.md b/doc/api_review/core/keyNew.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyNew.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyNextMeta.md b/doc/api_review/core/keyNextMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyNextMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyRewindMeta.md b/doc/api_review/core/keyRewindMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyRewindMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keySetBaseName.md b/doc/api_review/core/keySetBaseName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keySetBaseName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keySetBinary.md b/doc/api_review/core/keySetBinary.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keySetBinary.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keySetMeta.md b/doc/api_review/core/keySetMeta.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keySetMeta.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keySetName.md b/doc/api_review/core/keySetName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keySetName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keySetNamespace.md b/doc/api_review/core/keySetNamespace.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keySetNamespace.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keySetString.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyString.md b/doc/api_review/core/keyString.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyString.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyUnescapedName.md b/doc/api_review/core/keyUnescapedName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyUnescapedName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyVNew.md b/doc/api_review/core/keyVNew.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyVNew.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/keyValue.md b/doc/api_review/core/keyValue.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/keyValue.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksAppend.md b/doc/api_review/core/ksAppend.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksAppend.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksAppendKey.md b/doc/api_review/core/ksAppendKey.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksAppendKey.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksAtCursor.md b/doc/api_review/core/ksAtCursor.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksAtCursor.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksClear.md b/doc/api_review/core/ksClear.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksClear.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksCopy.md b/doc/api_review/core/ksCopy.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksCopy.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksCurrent.md b/doc/api_review/core/ksCurrent.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksCurrent.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksCut.md b/doc/api_review/core/ksCut.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksCut.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksDel.md b/doc/api_review/core/ksDel.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksDel.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksDup.md b/doc/api_review/core/ksDup.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksDup.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksGetCursor.md b/doc/api_review/core/ksGetCursor.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksGetCursor.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksGetSize.md b/doc/api_review/core/ksGetSize.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksGetSize.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksHead.md b/doc/api_review/core/ksHead.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksHead.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksLookup.md b/doc/api_review/core/ksLookup.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksLookup.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksLookupByName.md b/doc/api_review/core/ksLookupByName.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksLookupByName.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksNeedSync.md b/doc/api_review/core/ksNeedSync.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksNeedSync.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksNew.md b/doc/api_review/core/ksNew.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksNew.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksNext.md b/doc/api_review/core/ksNext.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksNext.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksPop.md b/doc/api_review/core/ksPop.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksPop.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksRewind.md b/doc/api_review/core/ksRewind.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksRewind.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksSetCursor.md b/doc/api_review/core/ksSetCursor.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksSetCursor.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksTail.md b/doc/api_review/core/ksTail.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksTail.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/doc/api_review/core/ksVNew.md b/doc/api_review/core/ksVNew.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/doc/api_review/core/ksVNew.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary diff --git a/scripts/api_review/.gitignore b/scripts/api_review/.gitignore new file mode 100644 index 00000000000..3fe20bec0f3 --- /dev/null +++ b/scripts/api_review/.gitignore @@ -0,0 +1 @@ +generated/ \ No newline at end of file diff --git a/scripts/api_review/README.md b/scripts/api_review/README.md new file mode 100644 index 00000000000..76c4ec7135a --- /dev/null +++ b/scripts/api_review/README.md @@ -0,0 +1,2 @@ +# Elektra API Review Template Script +This python script generates new review files from the given template. \ No newline at end of file diff --git a/scripts/api_review/generate_review_files.py b/scripts/api_review/generate_review_files.py new file mode 100644 index 00000000000..c092baeee5c --- /dev/null +++ b/scripts/api_review/generate_review_files.py @@ -0,0 +1,82 @@ +import re +import argparse +import sys +import os + +def print_error(message): + print(message) + sys.exit(1) + +def is_file(path): + if os.path.isfile(path): + return path + + print_error('File {} does not exist!'.format(path)) + +def is_folder(path): + if os.path.isdir(path): + return path + + print_error('Folder {} does not exist!'.format(path)) + +parser = argparse.ArgumentParser( + ''' + Generate review files from a markdown template + ''' +) + +parser.add_argument( + '-o', + '--output-folder', + help='Specify the output folder for the generated review files', + type=is_folder, + default='generated' +) + +parser.add_argument( + '-t', + '--template-path', + help='Specify the path for the template', + type=is_file, + default='template.md' +) + +parser.add_argument( + '-m', + '--methods-path', + help='Specify the path for the method list', + type=is_file, + default='methods.txt' +) + +args = parser.parse_args() + +def strip_method_name(method): + method = method.strip().rstrip(';') + method = re.sub('\s+', ' ', method) + + return method + + +def get_file_name(method, output_folder=args.output_folder): + return "{}/{}.md".format(output_folder, method) + + +def get_method_name(method): + method = method.split('(')[0] + method = method.split()[-1].strip().lstrip('*') + + return method + + +with open(args.methods_path, 'r') as methods_file: + methods = [strip_method_name(method) for method in methods_file] + +with open(args.template_path) as template_file: + template = template_file.read() + +for method in methods: + with open(get_file_name(get_method_name(method)), 'w') as output_file: + output_file.write( + template.format(signature_name = method) + ) \ No newline at end of file diff --git a/scripts/api_review/methods.txt b/scripts/api_review/methods.txt new file mode 100644 index 00000000000..6824869e86d --- /dev/null +++ b/scripts/api_review/methods.txt @@ -0,0 +1,74 @@ +KDB * kdbOpen(Key *errorKey); +int kdbClose(KDB *handle, Key *errorKey); +int kdbGet(KDB *handle, KeySet *returned, Key *parentKey); +int kdbSet(KDB *handle, KeySet *returned, Key *parentKey); +int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey); +Key *keyNew(const char *keyname, ...); +Key *keyVNew(const char *keyname, va_list ap); +Key *keyDup(const Key *source); +int keyCopy(Key *dest, const Key *source); +int keyClear(Key *key); +int keyDel(Key *key); +ssize_t keyIncRef(Key *key); +ssize_t keyDecRef(Key *key); +ssize_t keyGetRef(const Key *key); +int keyRewindMeta(Key *key); +const Key *keyNextMeta(Key *key); +const Key *keyCurrentMeta(const Key *key); +int keyCopyMeta(Key *dest, const Key *source, const char *metaName); +int keyCopyAllMeta(Key *dest, const Key *source); +const Key *keyGetMeta(const Key *key, const char* metaName); +ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString); +KeySet * keyMeta (Key * key); +int keyCmp(const Key *k1, const Key *k2); +int keyNeedSync(const Key *key); +int keyIsBelow(const Key *key, const Key *check); +int keyIsBelowOrSame(const Key *key, const Key *check); +int keyIsDirectlyBelow(const Key *key, const Key *check); +int keyIsBinary(const Key *key); +int keyIsString(const Key *key); +const char *keyName(const Key *key); +ssize_t keyGetNameSize(const Key *key); +ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize); +ssize_t keySetName(Key *key, const char *newname); +ssize_t keyAddName(Key *key, const char *addName); +const void *keyUnescapedName(const Key *key); +ssize_t keyGetUnescapedNameSize(const Key *key); +const char *keyBaseName(const Key *key); +ssize_t keyGetBaseNameSize(const Key *key); +ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize); +ssize_t keySetBaseName(Key *key,const char *baseName); +ssize_t keyAddBaseName(Key *key,const char *baseName); +elektraNamespace keyGetNamespace(Key const* key); +ssize_t keySetNamespace(Key * key, elektraNamespace ns); +const void *keyValue(const Key *key); +ssize_t keyGetValueSize(const Key *key); +const char *keyString(const Key *key); +ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize); +ssize_t keySetString(Key *key, const char *newString); +ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize); +ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize); +int keyLock (Key * key, elektraLockFlags what); +int keyIsLocked (const Key * key, elektraLockFlags what); +KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL; +KeySet *ksVNew(size_t alloc, va_list ap); +KeySet *ksDup(const KeySet * source); +int ksCopy(KeySet *dest, const KeySet *source); +int ksClear(KeySet *ks); +int ksDel(KeySet *ks); +int ksNeedSync(const KeySet *ks); +ssize_t ksGetSize(const KeySet *ks); +ssize_t ksAppendKey(KeySet *ks, Key *toAppend); +ssize_t ksAppend(KeySet *ks, const KeySet *toAppend); +KeySet *ksCut(KeySet *ks, const Key *cutpoint); +Key *ksPop(KeySet *ks); +int ksRewind(KeySet *ks); +Key *ksNext(KeySet *ks); +Key *ksCurrent(const KeySet *ks); +Key *ksHead(const KeySet *ks); +Key *ksTail(const KeySet *ks); +elektraCursor ksGetCursor(const KeySet *ks); +int ksSetCursor(KeySet *ks, elektraCursor cursor); +Key *ksAtCursor(KeySet *ks, elektraCursor cursor); +Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options); +Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options); diff --git a/scripts/api_review/template.md b/scripts/api_review/template.md new file mode 100644 index 00000000000..e7be4c446ad --- /dev/null +++ b/scripts/api_review/template.md @@ -0,0 +1,79 @@ +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- reviewer = Stefan Hanreich + + +## Checklist + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] No inconsistencies between documentation and tests +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Configuration flags are documented + +#### Doxygen + +- [ ] Precondition / Postcondition / Invariant +- [ ] `@retval` +- [ ] `@see` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] there is at least one example or snippet how to use the function + +### Naming + +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Functions should use constant types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Functions should have no side effects +- [ ] Configuration options are named constants +- [ ] Function belongs to appropriate group + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible +- [ ] Every memory allocation should be documented + +### Extensibility + +- [ ] Function is easily extensible with function flags (constants) +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Added functions are fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible configuration options are covered by tests +- [ ] Function body has full test coverage +- [ ] No inconsistencies between tests and documentation + + +## Summary From a937aaabb5b65b16a623e335103f1d7683c3cf56 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Sat, 13 Feb 2021 20:36:37 +0100 Subject: [PATCH 09/29] docs: improve template for api review - generate new api review blanks --- doc/api_review/core/kdbClose.md | 54 +++++++++++-------- doc/api_review/core/kdbEnsure.md | 54 +++++++++++-------- doc/api_review/core/kdbGet.md | 54 +++++++++++-------- doc/api_review/core/kdbOpen.md | 54 +++++++++++-------- doc/api_review/core/kdbSet.md | 54 +++++++++++-------- doc/api_review/core/keyAddBaseName.md | 54 +++++++++++-------- doc/api_review/core/keyAddName.md | 54 +++++++++++-------- doc/api_review/core/keyBaseName.md | 54 +++++++++++-------- doc/api_review/core/keyClear.md | 54 +++++++++++-------- doc/api_review/core/keyCmp.md | 54 +++++++++++-------- doc/api_review/core/keyCopy.md | 54 +++++++++++-------- doc/api_review/core/keyCopyAllMeta.md | 54 +++++++++++-------- doc/api_review/core/keyCopyMeta.md | 54 +++++++++++-------- doc/api_review/core/keyCurrentMeta.md | 54 +++++++++++-------- doc/api_review/core/keyDecRef.md | 54 +++++++++++-------- doc/api_review/core/keyDel.md | 54 +++++++++++-------- doc/api_review/core/keyDup.md | 54 +++++++++++-------- doc/api_review/core/keyGetBaseName.md | 54 +++++++++++-------- doc/api_review/core/keyGetBaseNameSize.md | 54 +++++++++++-------- doc/api_review/core/keyGetBinary.md | 54 +++++++++++-------- doc/api_review/core/keyGetMeta.md | 54 +++++++++++-------- doc/api_review/core/keyGetName.md | 54 +++++++++++-------- doc/api_review/core/keyGetNameSize.md | 54 +++++++++++-------- doc/api_review/core/keyGetNamespace.md | 54 +++++++++++-------- doc/api_review/core/keyGetRef.md | 54 +++++++++++-------- doc/api_review/core/keyGetString.md | 54 +++++++++++-------- .../core/keyGetUnescapedNameSize.md | 54 +++++++++++-------- doc/api_review/core/keyGetValueSize.md | 54 +++++++++++-------- doc/api_review/core/keyIncRef.md | 54 +++++++++++-------- doc/api_review/core/keyIsBelow.md | 54 +++++++++++-------- doc/api_review/core/keyIsBelowOrSame.md | 54 +++++++++++-------- doc/api_review/core/keyIsBinary.md | 54 +++++++++++-------- doc/api_review/core/keyIsDirectlyBelow.md | 54 +++++++++++-------- doc/api_review/core/keyIsLocked.md | 54 +++++++++++-------- doc/api_review/core/keyIsString.md | 54 +++++++++++-------- doc/api_review/core/keyLock.md | 54 +++++++++++-------- doc/api_review/core/keyMeta.md | 54 +++++++++++-------- doc/api_review/core/keyName.md | 54 +++++++++++-------- doc/api_review/core/keyNeedSync.md | 54 +++++++++++-------- doc/api_review/core/keyNew.md | 54 +++++++++++-------- doc/api_review/core/keyNextMeta.md | 54 +++++++++++-------- doc/api_review/core/keyRewindMeta.md | 54 +++++++++++-------- doc/api_review/core/keySetBaseName.md | 54 +++++++++++-------- doc/api_review/core/keySetBinary.md | 54 +++++++++++-------- doc/api_review/core/keySetMeta.md | 54 +++++++++++-------- doc/api_review/core/keySetName.md | 54 +++++++++++-------- doc/api_review/core/keySetNamespace.md | 54 +++++++++++-------- doc/api_review/core/keySetString.md | 54 +++++++++++-------- doc/api_review/core/keyString.md | 54 +++++++++++-------- doc/api_review/core/keyUnescapedName.md | 54 +++++++++++-------- doc/api_review/core/keyVNew.md | 54 +++++++++++-------- doc/api_review/core/keyValue.md | 54 +++++++++++-------- doc/api_review/core/ksAppend.md | 54 +++++++++++-------- doc/api_review/core/ksAppendKey.md | 54 +++++++++++-------- doc/api_review/core/ksAtCursor.md | 54 +++++++++++-------- doc/api_review/core/ksClear.md | 54 +++++++++++-------- doc/api_review/core/ksCopy.md | 54 +++++++++++-------- doc/api_review/core/ksCurrent.md | 54 +++++++++++-------- doc/api_review/core/ksCut.md | 54 +++++++++++-------- doc/api_review/core/ksDel.md | 54 +++++++++++-------- doc/api_review/core/ksDup.md | 54 +++++++++++-------- doc/api_review/core/ksGetCursor.md | 54 +++++++++++-------- doc/api_review/core/ksGetSize.md | 54 +++++++++++-------- doc/api_review/core/ksHead.md | 54 +++++++++++-------- doc/api_review/core/ksLookup.md | 54 +++++++++++-------- doc/api_review/core/ksLookupByName.md | 54 +++++++++++-------- doc/api_review/core/ksNeedSync.md | 54 +++++++++++-------- doc/api_review/core/ksNew.md | 54 +++++++++++-------- doc/api_review/core/ksNext.md | 54 +++++++++++-------- doc/api_review/core/ksPop.md | 54 +++++++++++-------- doc/api_review/core/ksRewind.md | 54 +++++++++++-------- doc/api_review/core/ksSetCursor.md | 54 +++++++++++-------- doc/api_review/core/ksTail.md | 54 +++++++++++-------- doc/api_review/core/ksVNew.md | 54 +++++++++++-------- scripts/api_review/generate_review_files.py | 6 ++- scripts/api_review/template.md | 54 +++++++++++-------- 76 files changed, 2329 insertions(+), 1727 deletions(-) diff --git a/doc/api_review/core/kdbClose.md b/doc/api_review/core/kdbClose.md index e7be4c446ad..aec510ae825 100644 --- a/doc/api_review/core/kdbClose.md +++ b/doc/api_review/core/kdbClose.md @@ -1,36 +1,45 @@ +# kdbClose + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int kdbClose(KDB *handle, Key *errorKey) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/kdbEnsure.md b/doc/api_review/core/kdbEnsure.md index e7be4c446ad..00ed64de371 100644 --- a/doc/api_review/core/kdbEnsure.md +++ b/doc/api_review/core/kdbEnsure.md @@ -1,36 +1,45 @@ +# kdbEnsure + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/kdbGet.md b/doc/api_review/core/kdbGet.md index e7be4c446ad..fb2881af92d 100644 --- a/doc/api_review/core/kdbGet.md +++ b/doc/api_review/core/kdbGet.md @@ -1,36 +1,45 @@ +# kdbGet + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/kdbOpen.md b/doc/api_review/core/kdbOpen.md index e7be4c446ad..2a2cdbf0839 100644 --- a/doc/api_review/core/kdbOpen.md +++ b/doc/api_review/core/kdbOpen.md @@ -1,36 +1,45 @@ +# kdbOpen + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +KDB * kdbOpen(Key *errorKey) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/kdbSet.md b/doc/api_review/core/kdbSet.md index e7be4c446ad..b4bf2d36c78 100644 --- a/doc/api_review/core/kdbSet.md +++ b/doc/api_review/core/kdbSet.md @@ -1,36 +1,45 @@ +# kdbSet + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyAddBaseName.md b/doc/api_review/core/keyAddBaseName.md index e7be4c446ad..9c90ead8cf0 100644 --- a/doc/api_review/core/keyAddBaseName.md +++ b/doc/api_review/core/keyAddBaseName.md @@ -1,36 +1,45 @@ +# keyAddBaseName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyAddBaseName(Key *key,const char *baseName) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyAddName.md b/doc/api_review/core/keyAddName.md index e7be4c446ad..9a9dca8cccd 100644 --- a/doc/api_review/core/keyAddName.md +++ b/doc/api_review/core/keyAddName.md @@ -1,36 +1,45 @@ +# keyAddName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyAddName(Key *key, const char *addName) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyBaseName.md b/doc/api_review/core/keyBaseName.md index e7be4c446ad..752190d4313 100644 --- a/doc/api_review/core/keyBaseName.md +++ b/doc/api_review/core/keyBaseName.md @@ -1,36 +1,45 @@ +# keyBaseName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const char *keyBaseName(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index e7be4c446ad..5880f61e527 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -1,36 +1,45 @@ +# keyClear + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyClear(Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyCmp.md b/doc/api_review/core/keyCmp.md index e7be4c446ad..7bf6be3c751 100644 --- a/doc/api_review/core/keyCmp.md +++ b/doc/api_review/core/keyCmp.md @@ -1,36 +1,45 @@ +# keyCmp + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyCmp(const Key *k1, const Key *k2) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyCopy.md b/doc/api_review/core/keyCopy.md index e7be4c446ad..e365daae8e2 100644 --- a/doc/api_review/core/keyCopy.md +++ b/doc/api_review/core/keyCopy.md @@ -1,36 +1,45 @@ +# keyCopy + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyCopy(Key *dest, const Key *source) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyCopyAllMeta.md b/doc/api_review/core/keyCopyAllMeta.md index e7be4c446ad..e2ab9caeadd 100644 --- a/doc/api_review/core/keyCopyAllMeta.md +++ b/doc/api_review/core/keyCopyAllMeta.md @@ -1,36 +1,45 @@ +# keyCopyAllMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyCopyAllMeta(Key *dest, const Key *source) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyCopyMeta.md b/doc/api_review/core/keyCopyMeta.md index e7be4c446ad..10bf01cf56d 100644 --- a/doc/api_review/core/keyCopyMeta.md +++ b/doc/api_review/core/keyCopyMeta.md @@ -1,36 +1,45 @@ +# keyCopyMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyCopyMeta(Key *dest, const Key *source, const char *metaName) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyCurrentMeta.md b/doc/api_review/core/keyCurrentMeta.md index e7be4c446ad..a6ae4e0e89e 100644 --- a/doc/api_review/core/keyCurrentMeta.md +++ b/doc/api_review/core/keyCurrentMeta.md @@ -1,36 +1,45 @@ +# keyCurrentMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const Key *keyCurrentMeta(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index e7be4c446ad..8b1378a175d 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -1,36 +1,45 @@ +# keyDecRef + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyDecRef(Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyDel.md b/doc/api_review/core/keyDel.md index e7be4c446ad..481459a1e6c 100644 --- a/doc/api_review/core/keyDel.md +++ b/doc/api_review/core/keyDel.md @@ -1,36 +1,45 @@ +# keyDel + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyDel(Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index e7be4c446ad..cc0c57f9061 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -1,36 +1,45 @@ +# keyDup + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *keyDup(const Key *source) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetBaseName.md b/doc/api_review/core/keyGetBaseName.md index e7be4c446ad..5a814f54ab7 100644 --- a/doc/api_review/core/keyGetBaseName.md +++ b/doc/api_review/core/keyGetBaseName.md @@ -1,36 +1,45 @@ +# keyGetBaseName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetBaseNameSize.md b/doc/api_review/core/keyGetBaseNameSize.md index e7be4c446ad..55b65a91113 100644 --- a/doc/api_review/core/keyGetBaseNameSize.md +++ b/doc/api_review/core/keyGetBaseNameSize.md @@ -1,36 +1,45 @@ +# keyGetBaseNameSize + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetBaseNameSize(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetBinary.md b/doc/api_review/core/keyGetBinary.md index e7be4c446ad..c4fada7169c 100644 --- a/doc/api_review/core/keyGetBinary.md +++ b/doc/api_review/core/keyGetBinary.md @@ -1,36 +1,45 @@ +# keyGetBinary + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetMeta.md b/doc/api_review/core/keyGetMeta.md index e7be4c446ad..0469b5bb629 100644 --- a/doc/api_review/core/keyGetMeta.md +++ b/doc/api_review/core/keyGetMeta.md @@ -1,36 +1,45 @@ +# keyGetMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const Key *keyGetMeta(const Key *key, const char* metaName) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index e7be4c446ad..4ec40c76a69 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -1,36 +1,45 @@ +# keyGetName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md index e7be4c446ad..77fa40b3c21 100644 --- a/doc/api_review/core/keyGetNameSize.md +++ b/doc/api_review/core/keyGetNameSize.md @@ -1,36 +1,45 @@ +# keyGetNameSize + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetNameSize(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetNamespace.md b/doc/api_review/core/keyGetNamespace.md index e7be4c446ad..8f0aa0b7774 100644 --- a/doc/api_review/core/keyGetNamespace.md +++ b/doc/api_review/core/keyGetNamespace.md @@ -1,36 +1,45 @@ +# keyGetNamespace + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +elektraNamespace keyGetNamespace(Key const* key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index e7be4c446ad..1a540a63c52 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -1,36 +1,45 @@ +# keyGetRef + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetRef(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetString.md b/doc/api_review/core/keyGetString.md index e7be4c446ad..d784b28d6ea 100644 --- a/doc/api_review/core/keyGetString.md +++ b/doc/api_review/core/keyGetString.md @@ -1,36 +1,45 @@ +# keyGetString + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetUnescapedNameSize.md b/doc/api_review/core/keyGetUnescapedNameSize.md index e7be4c446ad..18f3f48978a 100644 --- a/doc/api_review/core/keyGetUnescapedNameSize.md +++ b/doc/api_review/core/keyGetUnescapedNameSize.md @@ -1,36 +1,45 @@ +# keyGetUnescapedNameSize + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetUnescapedNameSize(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyGetValueSize.md b/doc/api_review/core/keyGetValueSize.md index e7be4c446ad..a0c1140327a 100644 --- a/doc/api_review/core/keyGetValueSize.md +++ b/doc/api_review/core/keyGetValueSize.md @@ -1,36 +1,45 @@ +# keyGetValueSize + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyGetValueSize(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index e7be4c446ad..e2e1ff3cf37 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -1,36 +1,45 @@ +# keyIncRef + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keyIncRef(Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyIsBelow.md b/doc/api_review/core/keyIsBelow.md index e7be4c446ad..f1bca13e38e 100644 --- a/doc/api_review/core/keyIsBelow.md +++ b/doc/api_review/core/keyIsBelow.md @@ -1,36 +1,45 @@ +# keyIsBelow + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyIsBelow(const Key *key, const Key *check) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyIsBelowOrSame.md b/doc/api_review/core/keyIsBelowOrSame.md index e7be4c446ad..98e6a1a08a2 100644 --- a/doc/api_review/core/keyIsBelowOrSame.md +++ b/doc/api_review/core/keyIsBelowOrSame.md @@ -1,36 +1,45 @@ +# keyIsBelowOrSame + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyIsBelowOrSame(const Key *key, const Key *check) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyIsBinary.md b/doc/api_review/core/keyIsBinary.md index e7be4c446ad..f1e8ca97893 100644 --- a/doc/api_review/core/keyIsBinary.md +++ b/doc/api_review/core/keyIsBinary.md @@ -1,36 +1,45 @@ +# keyIsBinary + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyIsBinary(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyIsDirectlyBelow.md b/doc/api_review/core/keyIsDirectlyBelow.md index e7be4c446ad..c1322bbfb35 100644 --- a/doc/api_review/core/keyIsDirectlyBelow.md +++ b/doc/api_review/core/keyIsDirectlyBelow.md @@ -1,36 +1,45 @@ +# keyIsDirectlyBelow + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyIsDirectlyBelow(const Key *key, const Key *check) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index e7be4c446ad..6355f5e2ae5 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -1,36 +1,45 @@ +# keyIsLocked + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyIsLocked (const Key * key, elektraLockFlags what) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyIsString.md b/doc/api_review/core/keyIsString.md index e7be4c446ad..c4c4973dbce 100644 --- a/doc/api_review/core/keyIsString.md +++ b/doc/api_review/core/keyIsString.md @@ -1,36 +1,45 @@ +# keyIsString + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyIsString(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index e7be4c446ad..80a8947a3b9 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -1,36 +1,45 @@ +# keyLock + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyLock (Key * key, elektraLockFlags what) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyMeta.md b/doc/api_review/core/keyMeta.md index e7be4c446ad..21f3fd4b439 100644 --- a/doc/api_review/core/keyMeta.md +++ b/doc/api_review/core/keyMeta.md @@ -1,36 +1,45 @@ +# keyMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +KeySet * keyMeta (Key * key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyName.md b/doc/api_review/core/keyName.md index e7be4c446ad..1e2001a4bb0 100644 --- a/doc/api_review/core/keyName.md +++ b/doc/api_review/core/keyName.md @@ -1,36 +1,45 @@ +# keyName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const char *keyName(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyNeedSync.md b/doc/api_review/core/keyNeedSync.md index e7be4c446ad..3134bf31a85 100644 --- a/doc/api_review/core/keyNeedSync.md +++ b/doc/api_review/core/keyNeedSync.md @@ -1,36 +1,45 @@ +# keyNeedSync + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyNeedSync(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyNew.md b/doc/api_review/core/keyNew.md index e7be4c446ad..c9e587b9054 100644 --- a/doc/api_review/core/keyNew.md +++ b/doc/api_review/core/keyNew.md @@ -1,36 +1,45 @@ +# keyNew + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *keyNew(const char *keyname, ...) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyNextMeta.md b/doc/api_review/core/keyNextMeta.md index e7be4c446ad..67b54349f43 100644 --- a/doc/api_review/core/keyNextMeta.md +++ b/doc/api_review/core/keyNextMeta.md @@ -1,36 +1,45 @@ +# keyNextMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const Key *keyNextMeta(Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyRewindMeta.md b/doc/api_review/core/keyRewindMeta.md index e7be4c446ad..4325dad9b99 100644 --- a/doc/api_review/core/keyRewindMeta.md +++ b/doc/api_review/core/keyRewindMeta.md @@ -1,36 +1,45 @@ +# keyRewindMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int keyRewindMeta(Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keySetBaseName.md b/doc/api_review/core/keySetBaseName.md index e7be4c446ad..e8fe24e7fce 100644 --- a/doc/api_review/core/keySetBaseName.md +++ b/doc/api_review/core/keySetBaseName.md @@ -1,36 +1,45 @@ +# keySetBaseName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keySetBaseName(Key *key,const char *baseName) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keySetBinary.md b/doc/api_review/core/keySetBinary.md index e7be4c446ad..0f03a9cac4f 100644 --- a/doc/api_review/core/keySetBinary.md +++ b/doc/api_review/core/keySetBinary.md @@ -1,36 +1,45 @@ +# keySetBinary + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keySetMeta.md b/doc/api_review/core/keySetMeta.md index e7be4c446ad..aea9f483b6c 100644 --- a/doc/api_review/core/keySetMeta.md +++ b/doc/api_review/core/keySetMeta.md @@ -1,36 +1,45 @@ +# keySetMeta + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keySetName.md b/doc/api_review/core/keySetName.md index e7be4c446ad..8ec8c920eec 100644 --- a/doc/api_review/core/keySetName.md +++ b/doc/api_review/core/keySetName.md @@ -1,36 +1,45 @@ +# keySetName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keySetName(Key *key, const char *newname) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keySetNamespace.md b/doc/api_review/core/keySetNamespace.md index e7be4c446ad..ee5690a5e7c 100644 --- a/doc/api_review/core/keySetNamespace.md +++ b/doc/api_review/core/keySetNamespace.md @@ -1,36 +1,45 @@ +# keySetNamespace + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keySetNamespace(Key * key, elektraNamespace ns) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index e7be4c446ad..e6f834dec83 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -1,36 +1,45 @@ +# keySetString + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t keySetString(Key *key, const char *newString) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyString.md b/doc/api_review/core/keyString.md index e7be4c446ad..f0e589ffbd0 100644 --- a/doc/api_review/core/keyString.md +++ b/doc/api_review/core/keyString.md @@ -1,36 +1,45 @@ +# keyString + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const char *keyString(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyUnescapedName.md b/doc/api_review/core/keyUnescapedName.md index e7be4c446ad..b0d658f6772 100644 --- a/doc/api_review/core/keyUnescapedName.md +++ b/doc/api_review/core/keyUnescapedName.md @@ -1,36 +1,45 @@ +# keyUnescapedName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const void *keyUnescapedName(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyVNew.md b/doc/api_review/core/keyVNew.md index e7be4c446ad..906ac291497 100644 --- a/doc/api_review/core/keyVNew.md +++ b/doc/api_review/core/keyVNew.md @@ -1,36 +1,45 @@ +# keyVNew + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *keyVNew(const char *keyname, va_list ap) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/keyValue.md b/doc/api_review/core/keyValue.md index e7be4c446ad..b4669dd0c92 100644 --- a/doc/api_review/core/keyValue.md +++ b/doc/api_review/core/keyValue.md @@ -1,36 +1,45 @@ +# keyValue + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +const void *keyValue(const Key *key) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksAppend.md b/doc/api_review/core/ksAppend.md index e7be4c446ad..8b6f57d0b2a 100644 --- a/doc/api_review/core/ksAppend.md +++ b/doc/api_review/core/ksAppend.md @@ -1,36 +1,45 @@ +# ksAppend + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksAppendKey.md b/doc/api_review/core/ksAppendKey.md index e7be4c446ad..d34c2efd8d5 100644 --- a/doc/api_review/core/ksAppendKey.md +++ b/doc/api_review/core/ksAppendKey.md @@ -1,36 +1,45 @@ +# ksAppendKey + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t ksAppendKey(KeySet *ks, Key *toAppend) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksAtCursor.md b/doc/api_review/core/ksAtCursor.md index e7be4c446ad..7ae960cb2e0 100644 --- a/doc/api_review/core/ksAtCursor.md +++ b/doc/api_review/core/ksAtCursor.md @@ -1,36 +1,45 @@ +# ksAtCursor + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksAtCursor(KeySet *ks, elektraCursor cursor) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksClear.md b/doc/api_review/core/ksClear.md index e7be4c446ad..69452581d1e 100644 --- a/doc/api_review/core/ksClear.md +++ b/doc/api_review/core/ksClear.md @@ -1,36 +1,45 @@ +# ksClear + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int ksClear(KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksCopy.md b/doc/api_review/core/ksCopy.md index e7be4c446ad..3f0e1cac49b 100644 --- a/doc/api_review/core/ksCopy.md +++ b/doc/api_review/core/ksCopy.md @@ -1,36 +1,45 @@ +# ksCopy + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int ksCopy(KeySet *dest, const KeySet *source) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksCurrent.md b/doc/api_review/core/ksCurrent.md index e7be4c446ad..edcee8f8450 100644 --- a/doc/api_review/core/ksCurrent.md +++ b/doc/api_review/core/ksCurrent.md @@ -1,36 +1,45 @@ +# ksCurrent + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksCurrent(const KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksCut.md b/doc/api_review/core/ksCut.md index e7be4c446ad..49d730a9698 100644 --- a/doc/api_review/core/ksCut.md +++ b/doc/api_review/core/ksCut.md @@ -1,36 +1,45 @@ +# ksCut + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +KeySet *ksCut(KeySet *ks, const Key *cutpoint) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksDel.md b/doc/api_review/core/ksDel.md index e7be4c446ad..4823c8b1db0 100644 --- a/doc/api_review/core/ksDel.md +++ b/doc/api_review/core/ksDel.md @@ -1,36 +1,45 @@ +# ksDel + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int ksDel(KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksDup.md b/doc/api_review/core/ksDup.md index e7be4c446ad..b47011a5992 100644 --- a/doc/api_review/core/ksDup.md +++ b/doc/api_review/core/ksDup.md @@ -1,36 +1,45 @@ +# ksDup + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +KeySet *ksDup(const KeySet * source) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksGetCursor.md b/doc/api_review/core/ksGetCursor.md index e7be4c446ad..03d0a265080 100644 --- a/doc/api_review/core/ksGetCursor.md +++ b/doc/api_review/core/ksGetCursor.md @@ -1,36 +1,45 @@ +# ksGetCursor + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +elektraCursor ksGetCursor(const KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksGetSize.md b/doc/api_review/core/ksGetSize.md index e7be4c446ad..55be14c7311 100644 --- a/doc/api_review/core/ksGetSize.md +++ b/doc/api_review/core/ksGetSize.md @@ -1,36 +1,45 @@ +# ksGetSize + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +ssize_t ksGetSize(const KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksHead.md b/doc/api_review/core/ksHead.md index e7be4c446ad..b23edde665a 100644 --- a/doc/api_review/core/ksHead.md +++ b/doc/api_review/core/ksHead.md @@ -1,36 +1,45 @@ +# ksHead + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksHead(const KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksLookup.md b/doc/api_review/core/ksLookup.md index e7be4c446ad..e5ad972e2c7 100644 --- a/doc/api_review/core/ksLookup.md +++ b/doc/api_review/core/ksLookup.md @@ -1,36 +1,45 @@ +# ksLookup + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksLookupByName.md b/doc/api_review/core/ksLookupByName.md index e7be4c446ad..9bd480d0a7c 100644 --- a/doc/api_review/core/ksLookupByName.md +++ b/doc/api_review/core/ksLookupByName.md @@ -1,36 +1,45 @@ +# ksLookupByName + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksNeedSync.md b/doc/api_review/core/ksNeedSync.md index e7be4c446ad..86a4cf83e30 100644 --- a/doc/api_review/core/ksNeedSync.md +++ b/doc/api_review/core/ksNeedSync.md @@ -1,36 +1,45 @@ +# ksNeedSync + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int ksNeedSync(const KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksNew.md b/doc/api_review/core/ksNew.md index e7be4c446ad..b3a166b1c58 100644 --- a/doc/api_review/core/ksNew.md +++ b/doc/api_review/core/ksNew.md @@ -1,36 +1,45 @@ +# ksNew + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksNext.md b/doc/api_review/core/ksNext.md index e7be4c446ad..0b10e2b6795 100644 --- a/doc/api_review/core/ksNext.md +++ b/doc/api_review/core/ksNext.md @@ -1,36 +1,45 @@ +# ksNext + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksNext(KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksPop.md b/doc/api_review/core/ksPop.md index e7be4c446ad..603e9b1a9aa 100644 --- a/doc/api_review/core/ksPop.md +++ b/doc/api_review/core/ksPop.md @@ -1,36 +1,45 @@ +# ksPop + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksPop(KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksRewind.md b/doc/api_review/core/ksRewind.md index e7be4c446ad..3b4c7d67ad5 100644 --- a/doc/api_review/core/ksRewind.md +++ b/doc/api_review/core/ksRewind.md @@ -1,36 +1,45 @@ +# ksRewind + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int ksRewind(KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksSetCursor.md b/doc/api_review/core/ksSetCursor.md index e7be4c446ad..941f6dfd5db 100644 --- a/doc/api_review/core/ksSetCursor.md +++ b/doc/api_review/core/ksSetCursor.md @@ -1,36 +1,45 @@ +# ksSetCursor + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +int ksSetCursor(KeySet *ks, elektraCursor cursor) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksTail.md b/doc/api_review/core/ksTail.md index e7be4c446ad..a009a5507dd 100644 --- a/doc/api_review/core/ksTail.md +++ b/doc/api_review/core/ksTail.md @@ -1,36 +1,45 @@ +# ksTail + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +Key *ksTail(const KeySet *ks) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/doc/api_review/core/ksVNew.md b/doc/api_review/core/ksVNew.md index e7be4c446ad..e83ef4ebf0d 100644 --- a/doc/api_review/core/ksVNew.md +++ b/doc/api_review/core/ksVNew.md @@ -1,36 +1,45 @@ +# ksVNew + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +KeySet *ksVNew(size_t alloc, va_list ap) -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary diff --git a/scripts/api_review/generate_review_files.py b/scripts/api_review/generate_review_files.py index c092baeee5c..0089086a016 100644 --- a/scripts/api_review/generate_review_files.py +++ b/scripts/api_review/generate_review_files.py @@ -76,7 +76,9 @@ def get_method_name(method): template = template_file.read() for method in methods: - with open(get_file_name(get_method_name(method)), 'w') as output_file: + method_name = get_method_name(method) + + with open(get_file_name(method_name), 'w') as output_file: output_file.write( - template.format(signature_name = method) + template.format(signature = method, name = method_name) ) \ No newline at end of file diff --git a/scripts/api_review/template.md b/scripts/api_review/template.md index e7be4c446ad..7c144167e27 100644 --- a/scripts/api_review/template.md +++ b/scripts/api_review/template.md @@ -1,36 +1,45 @@ +# {name} + - start = 2021-01-23 18:10 - end = 2021-01-23 18:10 -- reviewer = Stefan Hanreich - +- moderator = Stefan Hanreich -## Checklist -### Documentation +## Signature +{signature} -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented +## Checklist #### Doxygen -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` +- [ ] first line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function +- [ ] `@retval` +- [ ] good example or snippet how to use the function +- [ ] simple examples go first +- [ ] Precondition +- [ ] Postcondition +- [ ] Invariant +- [ ] `@param` for every parameter + +### Documentation + +- [ ] Change is mentioned in the Compatibility section of the release notes +- [ ] Proper Documentation of thread-safety of function +- [ ] All possible error states are documented +- [ ] Valid flags are documented ### Naming -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short - [ ] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous ### Compatibility @@ -44,7 +53,7 @@ - [ ] Functions should return the most specific type possible - [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types +- [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` @@ -53,27 +62,26 @@ ### Structural Clarity - [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group +- [ ] Function name has the appropriate prefix +- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented ### Extensibility -- [ ] Function is easily extensible with function flags (constants) +- [ ] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Added functions are fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage +- [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation +- [ ] Functions should have no side effects (idempotency) ## Summary From 5acdc3f0233498dc2ab262a6e8ebc5ebc0bcf3e4 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Mon, 15 Feb 2021 15:59:35 +0100 Subject: [PATCH 10/29] docs: capitalize beginning of sentences in api-review template, generate new files from template --- doc/api_review/core/kdbClose.md | 10 ++++++---- doc/api_review/core/kdbEnsure.md | 10 ++++++---- doc/api_review/core/kdbGet.md | 10 ++++++---- doc/api_review/core/kdbOpen.md | 10 ++++++---- doc/api_review/core/kdbSet.md | 10 ++++++---- doc/api_review/core/keyAddBaseName.md | 10 ++++++---- doc/api_review/core/keyAddName.md | 10 ++++++---- doc/api_review/core/keyBaseName.md | 10 ++++++---- doc/api_review/core/keyClear.md | 10 ++++++---- doc/api_review/core/keyCmp.md | 10 ++++++---- doc/api_review/core/keyCopy.md | 10 ++++++---- doc/api_review/core/keyCopyAllMeta.md | 10 ++++++---- doc/api_review/core/keyCopyMeta.md | 10 ++++++---- doc/api_review/core/keyCurrentMeta.md | 10 ++++++---- doc/api_review/core/keyDecRef.md | 10 ++++++---- doc/api_review/core/keyDel.md | 10 ++++++---- doc/api_review/core/keyDup.md | 10 ++++++---- doc/api_review/core/keyGetBaseName.md | 10 ++++++---- doc/api_review/core/keyGetBaseNameSize.md | 10 ++++++---- doc/api_review/core/keyGetBinary.md | 10 ++++++---- doc/api_review/core/keyGetMeta.md | 10 ++++++---- doc/api_review/core/keyGetName.md | 10 ++++++---- doc/api_review/core/keyGetNameSize.md | 10 ++++++---- doc/api_review/core/keyGetNamespace.md | 10 ++++++---- doc/api_review/core/keyGetRef.md | 10 ++++++---- doc/api_review/core/keyGetString.md | 10 ++++++---- doc/api_review/core/keyGetUnescapedNameSize.md | 10 ++++++---- doc/api_review/core/keyGetValueSize.md | 10 ++++++---- doc/api_review/core/keyIncRef.md | 10 ++++++---- doc/api_review/core/keyIsBelow.md | 10 ++++++---- doc/api_review/core/keyIsBelowOrSame.md | 10 ++++++---- doc/api_review/core/keyIsBinary.md | 10 ++++++---- doc/api_review/core/keyIsDirectlyBelow.md | 10 ++++++---- doc/api_review/core/keyIsLocked.md | 10 ++++++---- doc/api_review/core/keyIsString.md | 10 ++++++---- doc/api_review/core/keyLock.md | 10 ++++++---- doc/api_review/core/keyMeta.md | 10 ++++++---- doc/api_review/core/keyName.md | 10 ++++++---- doc/api_review/core/keyNeedSync.md | 10 ++++++---- doc/api_review/core/keyNew.md | 10 ++++++---- doc/api_review/core/keyNextMeta.md | 10 ++++++---- doc/api_review/core/keyRewindMeta.md | 10 ++++++---- doc/api_review/core/keySetBaseName.md | 10 ++++++---- doc/api_review/core/keySetBinary.md | 10 ++++++---- doc/api_review/core/keySetMeta.md | 10 ++++++---- doc/api_review/core/keySetName.md | 10 ++++++---- doc/api_review/core/keySetNamespace.md | 10 ++++++---- doc/api_review/core/keySetString.md | 10 ++++++---- doc/api_review/core/keyString.md | 10 ++++++---- doc/api_review/core/keyUnescapedName.md | 10 ++++++---- doc/api_review/core/keyVNew.md | 10 ++++++---- doc/api_review/core/keyValue.md | 10 ++++++---- doc/api_review/core/ksAppend.md | 10 ++++++---- doc/api_review/core/ksAppendKey.md | 10 ++++++---- doc/api_review/core/ksAtCursor.md | 10 ++++++---- doc/api_review/core/ksClear.md | 10 ++++++---- doc/api_review/core/ksCopy.md | 10 ++++++---- doc/api_review/core/ksCurrent.md | 10 ++++++---- doc/api_review/core/ksCut.md | 10 ++++++---- doc/api_review/core/ksDel.md | 10 ++++++---- doc/api_review/core/ksDup.md | 10 ++++++---- doc/api_review/core/ksGetCursor.md | 10 ++++++---- doc/api_review/core/ksGetSize.md | 10 ++++++---- doc/api_review/core/ksHead.md | 10 ++++++---- doc/api_review/core/ksLookup.md | 10 ++++++---- doc/api_review/core/ksLookupByName.md | 10 ++++++---- doc/api_review/core/ksNeedSync.md | 10 ++++++---- doc/api_review/core/ksNew.md | 10 ++++++---- doc/api_review/core/ksNext.md | 10 ++++++---- doc/api_review/core/ksPop.md | 10 ++++++---- doc/api_review/core/ksRewind.md | 10 ++++++---- doc/api_review/core/ksSetCursor.md | 10 ++++++---- doc/api_review/core/ksTail.md | 10 ++++++---- doc/api_review/core/ksVNew.md | 10 ++++++---- scripts/api_review/template.md | 10 ++++++---- 75 files changed, 450 insertions(+), 300 deletions(-) diff --git a/doc/api_review/core/kdbClose.md b/doc/api_review/core/kdbClose.md index aec510ae825..639f9177665 100644 --- a/doc/api_review/core/kdbClose.md +++ b/doc/api_review/core/kdbClose.md @@ -6,19 +6,21 @@ ## Signature + int kdbClose(KDB *handle, Key *errorKey) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int kdbClose(KDB *handle, Key *errorKey) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/kdbEnsure.md b/doc/api_review/core/kdbEnsure.md index 00ed64de371..8e795f90de0 100644 --- a/doc/api_review/core/kdbEnsure.md +++ b/doc/api_review/core/kdbEnsure.md @@ -6,19 +6,21 @@ ## Signature + int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/kdbGet.md b/doc/api_review/core/kdbGet.md index fb2881af92d..205359f5a13 100644 --- a/doc/api_review/core/kdbGet.md +++ b/doc/api_review/core/kdbGet.md @@ -6,19 +6,21 @@ ## Signature + int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/kdbOpen.md b/doc/api_review/core/kdbOpen.md index 2a2cdbf0839..d472e38d641 100644 --- a/doc/api_review/core/kdbOpen.md +++ b/doc/api_review/core/kdbOpen.md @@ -6,19 +6,21 @@ ## Signature + KDB * kdbOpen(Key *errorKey) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ KDB * kdbOpen(Key *errorKey) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/kdbSet.md b/doc/api_review/core/kdbSet.md index b4bf2d36c78..4659148cac2 100644 --- a/doc/api_review/core/kdbSet.md +++ b/doc/api_review/core/kdbSet.md @@ -6,19 +6,21 @@ ## Signature + int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyAddBaseName.md b/doc/api_review/core/keyAddBaseName.md index 9c90ead8cf0..524d608d9bb 100644 --- a/doc/api_review/core/keyAddBaseName.md +++ b/doc/api_review/core/keyAddBaseName.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyAddBaseName(Key *key,const char *baseName) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyAddBaseName(Key *key,const char *baseName) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyAddName.md b/doc/api_review/core/keyAddName.md index 9a9dca8cccd..fd897308ce9 100644 --- a/doc/api_review/core/keyAddName.md +++ b/doc/api_review/core/keyAddName.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyAddName(Key *key, const char *addName) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyAddName(Key *key, const char *addName) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyBaseName.md b/doc/api_review/core/keyBaseName.md index 752190d4313..2001d1fc262 100644 --- a/doc/api_review/core/keyBaseName.md +++ b/doc/api_review/core/keyBaseName.md @@ -6,19 +6,21 @@ ## Signature + const char *keyBaseName(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const char *keyBaseName(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index 5880f61e527..d99a150a317 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -6,19 +6,21 @@ ## Signature + int keyClear(Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyClear(Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyCmp.md b/doc/api_review/core/keyCmp.md index 7bf6be3c751..de3699a5ee3 100644 --- a/doc/api_review/core/keyCmp.md +++ b/doc/api_review/core/keyCmp.md @@ -6,19 +6,21 @@ ## Signature + int keyCmp(const Key *k1, const Key *k2) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyCmp(const Key *k1, const Key *k2) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyCopy.md b/doc/api_review/core/keyCopy.md index e365daae8e2..37987e8e08f 100644 --- a/doc/api_review/core/keyCopy.md +++ b/doc/api_review/core/keyCopy.md @@ -6,19 +6,21 @@ ## Signature + int keyCopy(Key *dest, const Key *source) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyCopy(Key *dest, const Key *source) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyCopyAllMeta.md b/doc/api_review/core/keyCopyAllMeta.md index e2ab9caeadd..e90c6322827 100644 --- a/doc/api_review/core/keyCopyAllMeta.md +++ b/doc/api_review/core/keyCopyAllMeta.md @@ -6,19 +6,21 @@ ## Signature + int keyCopyAllMeta(Key *dest, const Key *source) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyCopyAllMeta(Key *dest, const Key *source) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyCopyMeta.md b/doc/api_review/core/keyCopyMeta.md index 10bf01cf56d..d663a74ff70 100644 --- a/doc/api_review/core/keyCopyMeta.md +++ b/doc/api_review/core/keyCopyMeta.md @@ -6,19 +6,21 @@ ## Signature + int keyCopyMeta(Key *dest, const Key *source, const char *metaName) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyCopyMeta(Key *dest, const Key *source, const char *metaName) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyCurrentMeta.md b/doc/api_review/core/keyCurrentMeta.md index a6ae4e0e89e..85ef0d01bd0 100644 --- a/doc/api_review/core/keyCurrentMeta.md +++ b/doc/api_review/core/keyCurrentMeta.md @@ -6,19 +6,21 @@ ## Signature + const Key *keyCurrentMeta(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const Key *keyCurrentMeta(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index 8b1378a175d..1937fd78172 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyDecRef(Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyDecRef(Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyDel.md b/doc/api_review/core/keyDel.md index 481459a1e6c..1368219f99c 100644 --- a/doc/api_review/core/keyDel.md +++ b/doc/api_review/core/keyDel.md @@ -6,19 +6,21 @@ ## Signature + int keyDel(Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyDel(Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index cc0c57f9061..e062e1fd9a0 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -6,19 +6,21 @@ ## Signature + Key *keyDup(const Key *source) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *keyDup(const Key *source) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetBaseName.md b/doc/api_review/core/keyGetBaseName.md index 5a814f54ab7..b8d19533073 100644 --- a/doc/api_review/core/keyGetBaseName.md +++ b/doc/api_review/core/keyGetBaseName.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetBaseNameSize.md b/doc/api_review/core/keyGetBaseNameSize.md index 55b65a91113..787039d8b05 100644 --- a/doc/api_review/core/keyGetBaseNameSize.md +++ b/doc/api_review/core/keyGetBaseNameSize.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetBaseNameSize(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetBaseNameSize(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetBinary.md b/doc/api_review/core/keyGetBinary.md index c4fada7169c..d2917bc0378 100644 --- a/doc/api_review/core/keyGetBinary.md +++ b/doc/api_review/core/keyGetBinary.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetMeta.md b/doc/api_review/core/keyGetMeta.md index 0469b5bb629..55cd52cb0d7 100644 --- a/doc/api_review/core/keyGetMeta.md +++ b/doc/api_review/core/keyGetMeta.md @@ -6,19 +6,21 @@ ## Signature + const Key *keyGetMeta(const Key *key, const char* metaName) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const Key *keyGetMeta(const Key *key, const char* metaName) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index 4ec40c76a69..5ac0b58b81e 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md index 77fa40b3c21..df5c8ec9894 100644 --- a/doc/api_review/core/keyGetNameSize.md +++ b/doc/api_review/core/keyGetNameSize.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetNameSize(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetNameSize(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetNamespace.md b/doc/api_review/core/keyGetNamespace.md index 8f0aa0b7774..666abdb1cf5 100644 --- a/doc/api_review/core/keyGetNamespace.md +++ b/doc/api_review/core/keyGetNamespace.md @@ -6,19 +6,21 @@ ## Signature + elektraNamespace keyGetNamespace(Key const* key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ elektraNamespace keyGetNamespace(Key const* key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index 1a540a63c52..5c06136552c 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetRef(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetRef(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetString.md b/doc/api_review/core/keyGetString.md index d784b28d6ea..e4bd24924c9 100644 --- a/doc/api_review/core/keyGetString.md +++ b/doc/api_review/core/keyGetString.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetUnescapedNameSize.md b/doc/api_review/core/keyGetUnescapedNameSize.md index 18f3f48978a..cf79aaac089 100644 --- a/doc/api_review/core/keyGetUnescapedNameSize.md +++ b/doc/api_review/core/keyGetUnescapedNameSize.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetUnescapedNameSize(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetUnescapedNameSize(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetValueSize.md b/doc/api_review/core/keyGetValueSize.md index a0c1140327a..f07e0a47d0e 100644 --- a/doc/api_review/core/keyGetValueSize.md +++ b/doc/api_review/core/keyGetValueSize.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyGetValueSize(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyGetValueSize(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index e2e1ff3cf37..cb174ab1a55 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keyIncRef(Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keyIncRef(Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsBelow.md b/doc/api_review/core/keyIsBelow.md index f1bca13e38e..5f772eea18c 100644 --- a/doc/api_review/core/keyIsBelow.md +++ b/doc/api_review/core/keyIsBelow.md @@ -6,19 +6,21 @@ ## Signature + int keyIsBelow(const Key *key, const Key *check) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyIsBelow(const Key *key, const Key *check) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsBelowOrSame.md b/doc/api_review/core/keyIsBelowOrSame.md index 98e6a1a08a2..c2427061c0f 100644 --- a/doc/api_review/core/keyIsBelowOrSame.md +++ b/doc/api_review/core/keyIsBelowOrSame.md @@ -6,19 +6,21 @@ ## Signature + int keyIsBelowOrSame(const Key *key, const Key *check) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyIsBelowOrSame(const Key *key, const Key *check) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsBinary.md b/doc/api_review/core/keyIsBinary.md index f1e8ca97893..8b42a755d1d 100644 --- a/doc/api_review/core/keyIsBinary.md +++ b/doc/api_review/core/keyIsBinary.md @@ -6,19 +6,21 @@ ## Signature + int keyIsBinary(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyIsBinary(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsDirectlyBelow.md b/doc/api_review/core/keyIsDirectlyBelow.md index c1322bbfb35..9bc1e52fd50 100644 --- a/doc/api_review/core/keyIsDirectlyBelow.md +++ b/doc/api_review/core/keyIsDirectlyBelow.md @@ -6,19 +6,21 @@ ## Signature + int keyIsDirectlyBelow(const Key *key, const Key *check) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyIsDirectlyBelow(const Key *key, const Key *check) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index 6355f5e2ae5..61c4a771fb7 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -6,19 +6,21 @@ ## Signature + int keyIsLocked (const Key * key, elektraLockFlags what) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyIsLocked (const Key * key, elektraLockFlags what) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsString.md b/doc/api_review/core/keyIsString.md index c4c4973dbce..e765491e9d2 100644 --- a/doc/api_review/core/keyIsString.md +++ b/doc/api_review/core/keyIsString.md @@ -6,19 +6,21 @@ ## Signature + int keyIsString(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyIsString(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index 80a8947a3b9..700312e27ce 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -6,19 +6,21 @@ ## Signature + int keyLock (Key * key, elektraLockFlags what) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyLock (Key * key, elektraLockFlags what) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyMeta.md b/doc/api_review/core/keyMeta.md index 21f3fd4b439..d36739ab859 100644 --- a/doc/api_review/core/keyMeta.md +++ b/doc/api_review/core/keyMeta.md @@ -6,19 +6,21 @@ ## Signature + KeySet * keyMeta (Key * key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ KeySet * keyMeta (Key * key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyName.md b/doc/api_review/core/keyName.md index 1e2001a4bb0..8bd7b5bee75 100644 --- a/doc/api_review/core/keyName.md +++ b/doc/api_review/core/keyName.md @@ -6,19 +6,21 @@ ## Signature + const char *keyName(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const char *keyName(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyNeedSync.md b/doc/api_review/core/keyNeedSync.md index 3134bf31a85..697bd86025f 100644 --- a/doc/api_review/core/keyNeedSync.md +++ b/doc/api_review/core/keyNeedSync.md @@ -6,19 +6,21 @@ ## Signature + int keyNeedSync(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyNeedSync(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyNew.md b/doc/api_review/core/keyNew.md index c9e587b9054..625bb154ca4 100644 --- a/doc/api_review/core/keyNew.md +++ b/doc/api_review/core/keyNew.md @@ -6,19 +6,21 @@ ## Signature + Key *keyNew(const char *keyname, ...) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *keyNew(const char *keyname, ...) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyNextMeta.md b/doc/api_review/core/keyNextMeta.md index 67b54349f43..6e51cf5c743 100644 --- a/doc/api_review/core/keyNextMeta.md +++ b/doc/api_review/core/keyNextMeta.md @@ -6,19 +6,21 @@ ## Signature + const Key *keyNextMeta(Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const Key *keyNextMeta(Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyRewindMeta.md b/doc/api_review/core/keyRewindMeta.md index 4325dad9b99..ea8fc5f936d 100644 --- a/doc/api_review/core/keyRewindMeta.md +++ b/doc/api_review/core/keyRewindMeta.md @@ -6,19 +6,21 @@ ## Signature + int keyRewindMeta(Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int keyRewindMeta(Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetBaseName.md b/doc/api_review/core/keySetBaseName.md index e8fe24e7fce..48dd0e0d8d8 100644 --- a/doc/api_review/core/keySetBaseName.md +++ b/doc/api_review/core/keySetBaseName.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keySetBaseName(Key *key,const char *baseName) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keySetBaseName(Key *key,const char *baseName) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetBinary.md b/doc/api_review/core/keySetBinary.md index 0f03a9cac4f..e001c0437f3 100644 --- a/doc/api_review/core/keySetBinary.md +++ b/doc/api_review/core/keySetBinary.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetMeta.md b/doc/api_review/core/keySetMeta.md index aea9f483b6c..38e21d07f20 100644 --- a/doc/api_review/core/keySetMeta.md +++ b/doc/api_review/core/keySetMeta.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetName.md b/doc/api_review/core/keySetName.md index 8ec8c920eec..1b4266666c9 100644 --- a/doc/api_review/core/keySetName.md +++ b/doc/api_review/core/keySetName.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keySetName(Key *key, const char *newname) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keySetName(Key *key, const char *newname) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetNamespace.md b/doc/api_review/core/keySetNamespace.md index ee5690a5e7c..176e53c661f 100644 --- a/doc/api_review/core/keySetNamespace.md +++ b/doc/api_review/core/keySetNamespace.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keySetNamespace(Key * key, elektraNamespace ns) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keySetNamespace(Key * key, elektraNamespace ns) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index e6f834dec83..cd15e2203a1 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -6,19 +6,21 @@ ## Signature + ssize_t keySetString(Key *key, const char *newString) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t keySetString(Key *key, const char *newString) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyString.md b/doc/api_review/core/keyString.md index f0e589ffbd0..b539396529c 100644 --- a/doc/api_review/core/keyString.md +++ b/doc/api_review/core/keyString.md @@ -6,19 +6,21 @@ ## Signature + const char *keyString(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const char *keyString(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyUnescapedName.md b/doc/api_review/core/keyUnescapedName.md index b0d658f6772..032813dde7d 100644 --- a/doc/api_review/core/keyUnescapedName.md +++ b/doc/api_review/core/keyUnescapedName.md @@ -6,19 +6,21 @@ ## Signature + const void *keyUnescapedName(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const void *keyUnescapedName(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyVNew.md b/doc/api_review/core/keyVNew.md index 906ac291497..717715e987f 100644 --- a/doc/api_review/core/keyVNew.md +++ b/doc/api_review/core/keyVNew.md @@ -6,19 +6,21 @@ ## Signature + Key *keyVNew(const char *keyname, va_list ap) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *keyVNew(const char *keyname, va_list ap) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyValue.md b/doc/api_review/core/keyValue.md index b4669dd0c92..d1f6b0548e2 100644 --- a/doc/api_review/core/keyValue.md +++ b/doc/api_review/core/keyValue.md @@ -6,19 +6,21 @@ ## Signature + const void *keyValue(const Key *key) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ const void *keyValue(const Key *key) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksAppend.md b/doc/api_review/core/ksAppend.md index 8b6f57d0b2a..193ff6c73fc 100644 --- a/doc/api_review/core/ksAppend.md +++ b/doc/api_review/core/ksAppend.md @@ -6,19 +6,21 @@ ## Signature + ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksAppendKey.md b/doc/api_review/core/ksAppendKey.md index d34c2efd8d5..5efa8ab2a26 100644 --- a/doc/api_review/core/ksAppendKey.md +++ b/doc/api_review/core/ksAppendKey.md @@ -6,19 +6,21 @@ ## Signature + ssize_t ksAppendKey(KeySet *ks, Key *toAppend) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t ksAppendKey(KeySet *ks, Key *toAppend) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksAtCursor.md b/doc/api_review/core/ksAtCursor.md index 7ae960cb2e0..8487f7c392c 100644 --- a/doc/api_review/core/ksAtCursor.md +++ b/doc/api_review/core/ksAtCursor.md @@ -6,19 +6,21 @@ ## Signature + Key *ksAtCursor(KeySet *ks, elektraCursor cursor) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksAtCursor(KeySet *ks, elektraCursor cursor) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksClear.md b/doc/api_review/core/ksClear.md index 69452581d1e..b09b5a2a163 100644 --- a/doc/api_review/core/ksClear.md +++ b/doc/api_review/core/ksClear.md @@ -6,19 +6,21 @@ ## Signature + int ksClear(KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int ksClear(KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksCopy.md b/doc/api_review/core/ksCopy.md index 3f0e1cac49b..4feed74f372 100644 --- a/doc/api_review/core/ksCopy.md +++ b/doc/api_review/core/ksCopy.md @@ -6,19 +6,21 @@ ## Signature + int ksCopy(KeySet *dest, const KeySet *source) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int ksCopy(KeySet *dest, const KeySet *source) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksCurrent.md b/doc/api_review/core/ksCurrent.md index edcee8f8450..39fade6468f 100644 --- a/doc/api_review/core/ksCurrent.md +++ b/doc/api_review/core/ksCurrent.md @@ -6,19 +6,21 @@ ## Signature + Key *ksCurrent(const KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksCurrent(const KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksCut.md b/doc/api_review/core/ksCut.md index 49d730a9698..72fc9b253a7 100644 --- a/doc/api_review/core/ksCut.md +++ b/doc/api_review/core/ksCut.md @@ -6,19 +6,21 @@ ## Signature + KeySet *ksCut(KeySet *ks, const Key *cutpoint) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ KeySet *ksCut(KeySet *ks, const Key *cutpoint) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksDel.md b/doc/api_review/core/ksDel.md index 4823c8b1db0..d09bccff8d3 100644 --- a/doc/api_review/core/ksDel.md +++ b/doc/api_review/core/ksDel.md @@ -6,19 +6,21 @@ ## Signature + int ksDel(KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int ksDel(KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksDup.md b/doc/api_review/core/ksDup.md index b47011a5992..f045bc225be 100644 --- a/doc/api_review/core/ksDup.md +++ b/doc/api_review/core/ksDup.md @@ -6,19 +6,21 @@ ## Signature + KeySet *ksDup(const KeySet * source) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ KeySet *ksDup(const KeySet * source) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksGetCursor.md b/doc/api_review/core/ksGetCursor.md index 03d0a265080..6358d8648c9 100644 --- a/doc/api_review/core/ksGetCursor.md +++ b/doc/api_review/core/ksGetCursor.md @@ -6,19 +6,21 @@ ## Signature + elektraCursor ksGetCursor(const KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ elektraCursor ksGetCursor(const KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksGetSize.md b/doc/api_review/core/ksGetSize.md index 55be14c7311..c5ec12efae9 100644 --- a/doc/api_review/core/ksGetSize.md +++ b/doc/api_review/core/ksGetSize.md @@ -6,19 +6,21 @@ ## Signature + ssize_t ksGetSize(const KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ssize_t ksGetSize(const KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksHead.md b/doc/api_review/core/ksHead.md index b23edde665a..e23f3b8ee71 100644 --- a/doc/api_review/core/ksHead.md +++ b/doc/api_review/core/ksHead.md @@ -6,19 +6,21 @@ ## Signature + Key *ksHead(const KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksHead(const KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksLookup.md b/doc/api_review/core/ksLookup.md index e5ad972e2c7..09753b6ab3f 100644 --- a/doc/api_review/core/ksLookup.md +++ b/doc/api_review/core/ksLookup.md @@ -6,19 +6,21 @@ ## Signature + Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksLookupByName.md b/doc/api_review/core/ksLookupByName.md index 9bd480d0a7c..9e9555432b5 100644 --- a/doc/api_review/core/ksLookupByName.md +++ b/doc/api_review/core/ksLookupByName.md @@ -6,19 +6,21 @@ ## Signature + Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksNeedSync.md b/doc/api_review/core/ksNeedSync.md index 86a4cf83e30..39cbf567221 100644 --- a/doc/api_review/core/ksNeedSync.md +++ b/doc/api_review/core/ksNeedSync.md @@ -6,19 +6,21 @@ ## Signature + int ksNeedSync(const KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int ksNeedSync(const KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksNew.md b/doc/api_review/core/ksNew.md index b3a166b1c58..6e2b1916798 100644 --- a/doc/api_review/core/ksNew.md +++ b/doc/api_review/core/ksNew.md @@ -6,19 +6,21 @@ ## Signature + KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksNext.md b/doc/api_review/core/ksNext.md index 0b10e2b6795..385460feaed 100644 --- a/doc/api_review/core/ksNext.md +++ b/doc/api_review/core/ksNext.md @@ -6,19 +6,21 @@ ## Signature + Key *ksNext(KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksNext(KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksPop.md b/doc/api_review/core/ksPop.md index 603e9b1a9aa..3de4db1c47a 100644 --- a/doc/api_review/core/ksPop.md +++ b/doc/api_review/core/ksPop.md @@ -6,19 +6,21 @@ ## Signature + Key *ksPop(KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksPop(KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksRewind.md b/doc/api_review/core/ksRewind.md index 3b4c7d67ad5..408931e50b2 100644 --- a/doc/api_review/core/ksRewind.md +++ b/doc/api_review/core/ksRewind.md @@ -6,19 +6,21 @@ ## Signature + int ksRewind(KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int ksRewind(KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksSetCursor.md b/doc/api_review/core/ksSetCursor.md index 941f6dfd5db..8f901773504 100644 --- a/doc/api_review/core/ksSetCursor.md +++ b/doc/api_review/core/ksSetCursor.md @@ -6,19 +6,21 @@ ## Signature + int ksSetCursor(KeySet *ks, elektraCursor cursor) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ int ksSetCursor(KeySet *ks, elektraCursor cursor) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksTail.md b/doc/api_review/core/ksTail.md index a009a5507dd..c9c6fae16ba 100644 --- a/doc/api_review/core/ksTail.md +++ b/doc/api_review/core/ksTail.md @@ -6,19 +6,21 @@ ## Signature + Key *ksTail(const KeySet *ks) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ Key *ksTail(const KeySet *ks) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/ksVNew.md b/doc/api_review/core/ksVNew.md index e83ef4ebf0d..fe784cfddff 100644 --- a/doc/api_review/core/ksVNew.md +++ b/doc/api_review/core/ksVNew.md @@ -6,19 +6,21 @@ ## Signature + KeySet *ksVNew(size_t alloc, va_list ap) + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ KeySet *ksVNew(size_t alloc, va_list ap) ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation diff --git a/scripts/api_review/template.md b/scripts/api_review/template.md index 7c144167e27..3851af886f6 100644 --- a/scripts/api_review/template.md +++ b/scripts/api_review/template.md @@ -6,19 +6,21 @@ ## Signature + {signature} + ## Checklist #### Doxygen -- [ ] first line explains briefly what the function does +- [ ] First line explains briefly what the function does - [ ] `@see` - [ ] `@since` - [ ] `@ingroup` - [ ] `@retval` -- [ ] good example or snippet how to use the function -- [ ] simple examples go first +- [ ] Good example or snippet how to use the function +- [ ] Simple examples go first - [ ] Precondition - [ ] Postcondition - [ ] Invariant @@ -77,7 +79,7 @@ ### Tests -- [ ] Added functions are fully covered by tests +- [ ] Function code is fully covered by tests - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation From fe969fb5ca59df50e43a6300c0b46d4ee4f81965 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Sat, 20 Feb 2021 01:17:08 +0100 Subject: [PATCH 11/29] docs: add different review templates for different languages - regenerate templates - add first completed reviews --- doc/api_review/core/kdbClose.md | 36 ++---- doc/api_review/core/kdbEnsure.md | 36 ++---- doc/api_review/core/kdbGet.md | 36 ++---- doc/api_review/core/kdbOpen.md | 36 ++---- doc/api_review/core/kdbSet.md | 36 ++---- doc/api_review/core/keyAddBaseName.md | 36 ++---- doc/api_review/core/keyAddName.md | 36 ++---- doc/api_review/core/keyBaseName.md | 36 ++---- doc/api_review/core/keyClear.md | 36 ++---- doc/api_review/core/keyCmp.md | 36 ++---- doc/api_review/core/keyCopy.md | 36 ++---- doc/api_review/core/keyCopyAllMeta.md | 36 ++---- doc/api_review/core/keyCopyMeta.md | 36 ++---- doc/api_review/core/keyCurrentMeta.md | 36 ++---- doc/api_review/core/keyDecRef.md | 36 ++---- doc/api_review/core/keyDel.md | 103 ++++++++-------- doc/api_review/core/keyDup.md | 36 ++---- doc/api_review/core/keyGetBaseName.md | 36 ++---- doc/api_review/core/keyGetBaseNameSize.md | 36 ++---- doc/api_review/core/keyGetBinary.md | 36 ++---- doc/api_review/core/keyGetMeta.md | 36 ++---- doc/api_review/core/keyGetName.md | 36 ++---- doc/api_review/core/keyGetNameSize.md | 36 ++---- doc/api_review/core/keyGetNamespace.md | 36 ++---- doc/api_review/core/keyGetRef.md | 36 ++---- doc/api_review/core/keyGetString.md | 36 ++---- .../core/keyGetUnescapedNameSize.md | 36 ++---- doc/api_review/core/keyGetValueSize.md | 36 ++---- doc/api_review/core/keyIncRef.md | 36 ++---- doc/api_review/core/keyIsBelow.md | 36 ++---- doc/api_review/core/keyIsBelowOrSame.md | 36 ++---- doc/api_review/core/keyIsBinary.md | 36 ++---- doc/api_review/core/keyIsDirectlyBelow.md | 36 ++---- doc/api_review/core/keyIsLocked.md | 36 ++---- doc/api_review/core/keyIsString.md | 36 ++---- doc/api_review/core/keyLock.md | 36 ++---- doc/api_review/core/keyMeta.md | 36 ++---- doc/api_review/core/keyName.md | 103 ++++++++-------- doc/api_review/core/keyNeedSync.md | 36 ++---- doc/api_review/core/keyNew.md | 113 +++++++++-------- doc/api_review/core/keyNextMeta.md | 36 ++---- doc/api_review/core/keyRewindMeta.md | 36 ++---- doc/api_review/core/keySetBaseName.md | 36 ++---- doc/api_review/core/keySetBinary.md | 36 ++---- doc/api_review/core/keySetMeta.md | 36 ++---- doc/api_review/core/keySetName.md | 116 ++++++++++-------- doc/api_review/core/keySetNamespace.md | 36 ++---- doc/api_review/core/keySetString.md | 36 ++---- doc/api_review/core/keyString.md | 36 ++---- doc/api_review/core/keyUnescapedName.md | 36 ++---- doc/api_review/core/keyVNew.md | 36 ++---- doc/api_review/core/keyValue.md | 36 ++---- doc/api_review/core/ksAppend.md | 36 ++---- doc/api_review/core/ksAppendKey.md | 36 ++---- doc/api_review/core/ksAtCursor.md | 36 ++---- doc/api_review/core/ksClear.md | 36 ++---- doc/api_review/core/ksCopy.md | 36 ++---- doc/api_review/core/ksCurrent.md | 36 ++---- doc/api_review/core/ksCut.md | 36 ++---- doc/api_review/core/ksDel.md | 36 ++---- doc/api_review/core/ksDup.md | 36 ++---- doc/api_review/core/ksGetCursor.md | 36 ++---- doc/api_review/core/ksGetSize.md | 36 ++---- doc/api_review/core/ksHead.md | 36 ++---- doc/api_review/core/ksLookup.md | 36 ++---- doc/api_review/core/ksLookupByName.md | 36 ++---- doc/api_review/core/ksNeedSync.md | 36 ++---- doc/api_review/core/ksNew.md | 36 ++---- doc/api_review/core/ksNext.md | 36 ++---- doc/api_review/core/ksPop.md | 36 ++---- doc/api_review/core/ksRewind.md | 36 ++---- doc/api_review/core/ksSetCursor.md | 36 ++---- doc/api_review/core/ksTail.md | 36 ++---- doc/api_review/core/ksVNew.md | 36 ++---- scripts/api_review/generate_review_files.py | 4 +- .../api_review/{methods.txt => methods.c.txt} | 0 scripts/api_review/template.c.md | 79 ++++++++++++ .../{template.md => template.java.md} | 29 ++--- scripts/api_review/template.rs.md | 81 ++++++++++++ 79 files changed, 1310 insertions(+), 1838 deletions(-) rename scripts/api_review/{methods.txt => methods.c.txt} (100%) create mode 100644 scripts/api_review/template.c.md rename scripts/api_review/{template.md => template.java.md} (80%) create mode 100644 scripts/api_review/template.rs.md diff --git a/doc/api_review/core/kdbClose.md b/doc/api_review/core/kdbClose.md index 639f9177665..ae4b9e0acb6 100644 --- a/doc/api_review/core/kdbClose.md +++ b/doc/api_review/core/kdbClose.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int kdbClose(KDB *handle, Key *errorKey) - +`int kdbClose(KDB *handle, Key *errorKey)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int kdbClose(KDB *handle, Key *errorKey) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int kdbClose(KDB *handle, Key *errorKey) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int kdbClose(KDB *handle, Key *errorKey) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int kdbClose(KDB *handle, Key *errorKey) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/kdbEnsure.md b/doc/api_review/core/kdbEnsure.md index 8e795f90de0..fbaa786d946 100644 --- a/doc/api_review/core/kdbEnsure.md +++ b/doc/api_review/core/kdbEnsure.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) - +`int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/kdbGet.md b/doc/api_review/core/kdbGet.md index 205359f5a13..af8e8a8df50 100644 --- a/doc/api_review/core/kdbGet.md +++ b/doc/api_review/core/kdbGet.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) - +`int kdbGet(KDB *handle, KeySet *returned, Key *parentKey)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int kdbGet(KDB *handle, KeySet *returned, Key *parentKey) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/kdbOpen.md b/doc/api_review/core/kdbOpen.md index d472e38d641..8108bc892b6 100644 --- a/doc/api_review/core/kdbOpen.md +++ b/doc/api_review/core/kdbOpen.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -KDB * kdbOpen(Key *errorKey) - +`KDB * kdbOpen(Key *errorKey)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ KDB * kdbOpen(Key *errorKey) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ KDB * kdbOpen(Key *errorKey) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ KDB * kdbOpen(Key *errorKey) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ KDB * kdbOpen(Key *errorKey) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/kdbSet.md b/doc/api_review/core/kdbSet.md index 4659148cac2..3682686cdec 100644 --- a/doc/api_review/core/kdbSet.md +++ b/doc/api_review/core/kdbSet.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) - +`int kdbSet(KDB *handle, KeySet *returned, Key *parentKey)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int kdbSet(KDB *handle, KeySet *returned, Key *parentKey) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyAddBaseName.md b/doc/api_review/core/keyAddBaseName.md index 524d608d9bb..13159ded53a 100644 --- a/doc/api_review/core/keyAddBaseName.md +++ b/doc/api_review/core/keyAddBaseName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyAddBaseName(Key *key,const char *baseName) - +`ssize_t keyAddBaseName(Key *key,const char *baseName)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyAddBaseName(Key *key,const char *baseName) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyAddBaseName(Key *key,const char *baseName) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyAddBaseName(Key *key,const char *baseName) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyAddBaseName(Key *key,const char *baseName) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyAddName.md b/doc/api_review/core/keyAddName.md index fd897308ce9..5aab1f2154e 100644 --- a/doc/api_review/core/keyAddName.md +++ b/doc/api_review/core/keyAddName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyAddName(Key *key, const char *addName) - +`ssize_t keyAddName(Key *key, const char *addName)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyAddName(Key *key, const char *addName) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyAddName(Key *key, const char *addName) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyAddName(Key *key, const char *addName) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyAddName(Key *key, const char *addName) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyBaseName.md b/doc/api_review/core/keyBaseName.md index 2001d1fc262..3113867e1bd 100644 --- a/doc/api_review/core/keyBaseName.md +++ b/doc/api_review/core/keyBaseName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -const char *keyBaseName(const Key *key) - +`const char *keyBaseName(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ const char *keyBaseName(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ const char *keyBaseName(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ const char *keyBaseName(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ const char *keyBaseName(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index d99a150a317..e0b3ae3efad 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyClear(Key *key) - +`int keyClear(Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyClear(Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyClear(Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyClear(Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyClear(Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyCmp.md b/doc/api_review/core/keyCmp.md index de3699a5ee3..9ddbe69beaf 100644 --- a/doc/api_review/core/keyCmp.md +++ b/doc/api_review/core/keyCmp.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyCmp(const Key *k1, const Key *k2) - +`int keyCmp(const Key *k1, const Key *k2)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyCmp(const Key *k1, const Key *k2) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyCmp(const Key *k1, const Key *k2) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyCmp(const Key *k1, const Key *k2) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyCmp(const Key *k1, const Key *k2) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyCopy.md b/doc/api_review/core/keyCopy.md index 37987e8e08f..0b5d51fc51a 100644 --- a/doc/api_review/core/keyCopy.md +++ b/doc/api_review/core/keyCopy.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyCopy(Key *dest, const Key *source) - +`int keyCopy(Key *dest, const Key *source)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyCopy(Key *dest, const Key *source) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyCopy(Key *dest, const Key *source) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyCopy(Key *dest, const Key *source) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyCopy(Key *dest, const Key *source) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyCopyAllMeta.md b/doc/api_review/core/keyCopyAllMeta.md index e90c6322827..167f5298aca 100644 --- a/doc/api_review/core/keyCopyAllMeta.md +++ b/doc/api_review/core/keyCopyAllMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyCopyAllMeta(Key *dest, const Key *source) - +`int keyCopyAllMeta(Key *dest, const Key *source)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyCopyAllMeta(Key *dest, const Key *source) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyCopyAllMeta(Key *dest, const Key *source) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyCopyAllMeta(Key *dest, const Key *source) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyCopyAllMeta(Key *dest, const Key *source) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyCopyMeta.md b/doc/api_review/core/keyCopyMeta.md index d663a74ff70..23ba7e855cb 100644 --- a/doc/api_review/core/keyCopyMeta.md +++ b/doc/api_review/core/keyCopyMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyCopyMeta(Key *dest, const Key *source, const char *metaName) - +`int keyCopyMeta(Key *dest, const Key *source, const char *metaName)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyCopyMeta(Key *dest, const Key *source, const char *metaName) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyCopyMeta(Key *dest, const Key *source, const char *metaName) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyCopyMeta(Key *dest, const Key *source, const char *metaName) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyCopyMeta(Key *dest, const Key *source, const char *metaName) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyCurrentMeta.md b/doc/api_review/core/keyCurrentMeta.md index 85ef0d01bd0..b281eaea769 100644 --- a/doc/api_review/core/keyCurrentMeta.md +++ b/doc/api_review/core/keyCurrentMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -const Key *keyCurrentMeta(const Key *key) - +`const Key *keyCurrentMeta(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ const Key *keyCurrentMeta(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ const Key *keyCurrentMeta(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ const Key *keyCurrentMeta(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ const Key *keyCurrentMeta(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index 1937fd78172..3de96fcfc1d 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyDecRef(Key *key) - +`ssize_t keyDecRef(Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyDecRef(Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyDecRef(Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyDecRef(Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyDecRef(Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyDel.md b/doc/api_review/core/keyDel.md index 1368219f99c..23f405aca94 100644 --- a/doc/api_review/core/keyDel.md +++ b/doc/api_review/core/keyDel.md @@ -1,89 +1,88 @@ # keyDel -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 -- moderator = Stefan Hanreich - +- start = 2021-02-14 03:55 +- end = 2021-02-14 04:25 +- reviewer = Stefan Hanreich ## Signature -int keyDel(Key *key) - +`int keyDel(Key *key)` ## Checklist #### Doxygen - -- [ ] First line explains briefly what the function does -- [ ] `@see` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +(bullet points are in order of appearance) + +- [x] First line explains briefly what the function does +- [ ] Simple example or snippet how to use the function + - [ ] add example +- [x] Longer description of function containing common use cases +- [x] Description of functions reads nicely +- [ ] `@pre` + - [ ] @pre Key must not be null +- [ ] `@post` + - [ ] @post Key memory has been freed +- [ ] `@invariant + - [ ] add (tbd) +- [x] `@param` for every parameter +- [ ] `@return` / `@retval` + - [ ] `0` when the key was freed and no references are held in keysets +- [ ] `@since` + - [ ] add +- [x] `@ingroup` +- [x] `@see` ### Naming -- [ ] Abbreviations used in function names must be defined in the +- [x] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible -- [ ] Function parameters should use enum types instead of boolean types +- [x] Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` + - [ ] could maybe change this to const +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [ ] Order of signatures in kdb.h.in is the same as Doxygen + - [ ] swap keyClear and keyDel +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] TBD cannot change behaviour of referenced keys ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - +- [x] Function code is fully covered by tests +- [x] All possible error states are covered by tests +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index e062e1fd9a0..639e56f954b 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *keyDup(const Key *source) - +`Key *keyDup(const Key *source)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *keyDup(const Key *source) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *keyDup(const Key *source) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *keyDup(const Key *source) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *keyDup(const Key *source) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetBaseName.md b/doc/api_review/core/keyGetBaseName.md index b8d19533073..3ae63635e81 100644 --- a/doc/api_review/core/keyGetBaseName.md +++ b/doc/api_review/core/keyGetBaseName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) - +`ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetBaseName(const Key *key, char *returned, size_t maxSize) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetBaseNameSize.md b/doc/api_review/core/keyGetBaseNameSize.md index 787039d8b05..1ed61816578 100644 --- a/doc/api_review/core/keyGetBaseNameSize.md +++ b/doc/api_review/core/keyGetBaseNameSize.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetBaseNameSize(const Key *key) - +`ssize_t keyGetBaseNameSize(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetBaseNameSize(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetBaseNameSize(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetBaseNameSize(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetBaseNameSize(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetBinary.md b/doc/api_review/core/keyGetBinary.md index d2917bc0378..879fe374de5 100644 --- a/doc/api_review/core/keyGetBinary.md +++ b/doc/api_review/core/keyGetBinary.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) - +`ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetMeta.md b/doc/api_review/core/keyGetMeta.md index 55cd52cb0d7..c1d660a8560 100644 --- a/doc/api_review/core/keyGetMeta.md +++ b/doc/api_review/core/keyGetMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -const Key *keyGetMeta(const Key *key, const char* metaName) - +`const Key *keyGetMeta(const Key *key, const char* metaName)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ const Key *keyGetMeta(const Key *key, const char* metaName) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ const Key *keyGetMeta(const Key *key, const char* metaName) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ const Key *keyGetMeta(const Key *key, const char* metaName) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ const Key *keyGetMeta(const Key *key, const char* metaName) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index 5ac0b58b81e..6c94cabd426 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) - +`ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetName(const Key *key, char *returnedName, size_t maxSize) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md index df5c8ec9894..9a86c0ff0dd 100644 --- a/doc/api_review/core/keyGetNameSize.md +++ b/doc/api_review/core/keyGetNameSize.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetNameSize(const Key *key) - +`ssize_t keyGetNameSize(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetNameSize(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetNameSize(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetNameSize(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetNameSize(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetNamespace.md b/doc/api_review/core/keyGetNamespace.md index 666abdb1cf5..5b26d28d685 100644 --- a/doc/api_review/core/keyGetNamespace.md +++ b/doc/api_review/core/keyGetNamespace.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -elektraNamespace keyGetNamespace(Key const* key) - +`elektraNamespace keyGetNamespace(Key const* key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ elektraNamespace keyGetNamespace(Key const* key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ elektraNamespace keyGetNamespace(Key const* key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ elektraNamespace keyGetNamespace(Key const* key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ elektraNamespace keyGetNamespace(Key const* key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index 5c06136552c..40b717c750f 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetRef(const Key *key) - +`ssize_t keyGetRef(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetRef(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetRef(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetRef(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetRef(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetString.md b/doc/api_review/core/keyGetString.md index e4bd24924c9..53c552cf42b 100644 --- a/doc/api_review/core/keyGetString.md +++ b/doc/api_review/core/keyGetString.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) - +`ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetUnescapedNameSize.md b/doc/api_review/core/keyGetUnescapedNameSize.md index cf79aaac089..736cb132cde 100644 --- a/doc/api_review/core/keyGetUnescapedNameSize.md +++ b/doc/api_review/core/keyGetUnescapedNameSize.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetUnescapedNameSize(const Key *key) - +`ssize_t keyGetUnescapedNameSize(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetUnescapedNameSize(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetUnescapedNameSize(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetUnescapedNameSize(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetUnescapedNameSize(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyGetValueSize.md b/doc/api_review/core/keyGetValueSize.md index f07e0a47d0e..f327d50fc28 100644 --- a/doc/api_review/core/keyGetValueSize.md +++ b/doc/api_review/core/keyGetValueSize.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyGetValueSize(const Key *key) - +`ssize_t keyGetValueSize(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyGetValueSize(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyGetValueSize(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyGetValueSize(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyGetValueSize(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index cb174ab1a55..a952c3b1794 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keyIncRef(Key *key) - +`ssize_t keyIncRef(Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keyIncRef(Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keyIncRef(Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keyIncRef(Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keyIncRef(Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyIsBelow.md b/doc/api_review/core/keyIsBelow.md index 5f772eea18c..3930d787d11 100644 --- a/doc/api_review/core/keyIsBelow.md +++ b/doc/api_review/core/keyIsBelow.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyIsBelow(const Key *key, const Key *check) - +`int keyIsBelow(const Key *key, const Key *check)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyIsBelow(const Key *key, const Key *check) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyIsBelow(const Key *key, const Key *check) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyIsBelow(const Key *key, const Key *check) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyIsBelow(const Key *key, const Key *check) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyIsBelowOrSame.md b/doc/api_review/core/keyIsBelowOrSame.md index c2427061c0f..0b1a10241e3 100644 --- a/doc/api_review/core/keyIsBelowOrSame.md +++ b/doc/api_review/core/keyIsBelowOrSame.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyIsBelowOrSame(const Key *key, const Key *check) - +`int keyIsBelowOrSame(const Key *key, const Key *check)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyIsBelowOrSame(const Key *key, const Key *check) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyIsBelowOrSame(const Key *key, const Key *check) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyIsBelowOrSame(const Key *key, const Key *check) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyIsBelowOrSame(const Key *key, const Key *check) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyIsBinary.md b/doc/api_review/core/keyIsBinary.md index 8b42a755d1d..87f86566b41 100644 --- a/doc/api_review/core/keyIsBinary.md +++ b/doc/api_review/core/keyIsBinary.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyIsBinary(const Key *key) - +`int keyIsBinary(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyIsBinary(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyIsBinary(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyIsBinary(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyIsBinary(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyIsDirectlyBelow.md b/doc/api_review/core/keyIsDirectlyBelow.md index 9bc1e52fd50..12bc1270b23 100644 --- a/doc/api_review/core/keyIsDirectlyBelow.md +++ b/doc/api_review/core/keyIsDirectlyBelow.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyIsDirectlyBelow(const Key *key, const Key *check) - +`int keyIsDirectlyBelow(const Key *key, const Key *check)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyIsDirectlyBelow(const Key *key, const Key *check) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyIsDirectlyBelow(const Key *key, const Key *check) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyIsDirectlyBelow(const Key *key, const Key *check) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyIsDirectlyBelow(const Key *key, const Key *check) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index 61c4a771fb7..badb03820ed 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyIsLocked (const Key * key, elektraLockFlags what) - +`int keyIsLocked (const Key * key, elektraLockFlags what)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyIsLocked (const Key * key, elektraLockFlags what) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyIsLocked (const Key * key, elektraLockFlags what) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyIsLocked (const Key * key, elektraLockFlags what) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyIsLocked (const Key * key, elektraLockFlags what) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyIsString.md b/doc/api_review/core/keyIsString.md index e765491e9d2..158d0cdae6c 100644 --- a/doc/api_review/core/keyIsString.md +++ b/doc/api_review/core/keyIsString.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyIsString(const Key *key) - +`int keyIsString(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyIsString(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyIsString(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyIsString(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyIsString(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index 700312e27ce..1992ab6d0f4 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyLock (Key * key, elektraLockFlags what) - +`int keyLock (Key * key, elektraLockFlags what)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyLock (Key * key, elektraLockFlags what) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyLock (Key * key, elektraLockFlags what) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyLock (Key * key, elektraLockFlags what) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyLock (Key * key, elektraLockFlags what) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyMeta.md b/doc/api_review/core/keyMeta.md index d36739ab859..43503fe6d5e 100644 --- a/doc/api_review/core/keyMeta.md +++ b/doc/api_review/core/keyMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -KeySet * keyMeta (Key * key) - +`KeySet * keyMeta (Key * key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ KeySet * keyMeta (Key * key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ KeySet * keyMeta (Key * key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ KeySet * keyMeta (Key * key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ KeySet * keyMeta (Key * key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyName.md b/doc/api_review/core/keyName.md index 8bd7b5bee75..1e2dca8f611 100644 --- a/doc/api_review/core/keyName.md +++ b/doc/api_review/core/keyName.md @@ -1,89 +1,88 @@ # keyName -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 -- moderator = Stefan Hanreich - +- start = 2021-02-14 02:12 +- end = 2021-02-14 02:44 +- reviewer = Stefan Hanreich ## Signature -const char *keyName(const Key *key) - +`const char *keyName(const Key *key)` ## Checklist #### Doxygen - -- [ ] First line explains briefly what the function does -- [ ] `@see` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +(bullet points are in order of appearance) + +- [x] First line explains briefly what the function does +- [x] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` + - [ ] @pre key must be a valid key +- [ ] `@post` + - [ ] @post Pointer to key that can change over time +- [ ] `@invariant` + - [ ] key name stays valid +- [x] `@param` for every parameter +- [ ] `@return` / `@retval` + - [ ] add default return value to `@retval` +- [ ] `@since` + - [ ] add +- [x] `@ingroup` +- [x] `@see` ### Naming -- [ ] Abbreviations used in function names must be defined in the +- [x] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the +- [x] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous + - [ ] Function name might lead to confusions with `keyGetName()`, make + their intentions more clear in their names +- [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible -- [ ] Function parameters should use enum types instead of boolean types +- Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist + - [ ] `keyUnescapedName` might be considered too similar ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [x] Documentation does not impose limits, that would hinder further extensions ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - +- [x] Function code is fully covered by tests +- [ ] All possible error states are covered by tests + - [ ] empty keyName is not covered in tests +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyNeedSync.md b/doc/api_review/core/keyNeedSync.md index 697bd86025f..b18fdce04ae 100644 --- a/doc/api_review/core/keyNeedSync.md +++ b/doc/api_review/core/keyNeedSync.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyNeedSync(const Key *key) - +`int keyNeedSync(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyNeedSync(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyNeedSync(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyNeedSync(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyNeedSync(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyNew.md b/doc/api_review/core/keyNew.md index 625bb154ca4..e7466b62875 100644 --- a/doc/api_review/core/keyNew.md +++ b/doc/api_review/core/keyNew.md @@ -1,89 +1,98 @@ # keyNew -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 -- moderator = Stefan Hanreich - +- start = 2021-02-14 02:55 +- end = 2021-02-14 03:22 +- reviewer = Stefan Hanreich ## Signature -Key *keyNew(const char *keyname, ...) - +`Key *keyNew(const char *keyname, ...)` ## Checklist #### Doxygen - -- [ ] First line explains briefly what the function does -- [ ] `@see` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +(bullet points are in order of appearance) + +- [x] First line explains briefly what the function does +- [x] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases + - [ ] is 0 a valid name? returns NULL if 0 is param +- [x] Description of functions reads nicely +- [ ] `@pre` + - [ ] @pre name must be a valid key name +- [ ] `@post` + - [ ] @post returns a valid key object +- [ ] `@invariant` + - [ ] add +- [ ] `@param` for every parameter + - [ ] add `@param` for `...` +- [x] `@return` / `@retval` +- [ ] `@since` + - [ ] add +- [x] `@ingroup` +- [x] `@see` ### Naming -- [ ] Abbreviations used in function names must be defined in the +- [x] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible -- [ ] Function parameters should use enum types instead of boolean types +- [x] Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing + - it doesn't technically - but its a convenience function +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] Docs say `Key *k = keyNew(0);` has same effect + as `Key *k =keyNew("", KEY_END);` ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - +- [x] Function code is fully covered by tests +- [x] All possible error states are covered by tests +- [ ] All possible enum values are covered by tests + - [ ] KEY_META + - [ ] KEY_FLAGS +- [ ] No inconsistencies between tests and documentation + - [ ] Documentation says i can work with `Key *k =keyNew("", KEY_END);` + Tests say + ``` + k = keyNew ("", KEY_END); + succeed_if (k == NULL, "should be invalid"); + keyDel (k); + ``` + - [ ] same as above with `keyNew(0)` ## Summary diff --git a/doc/api_review/core/keyNextMeta.md b/doc/api_review/core/keyNextMeta.md index 6e51cf5c743..10e218b453b 100644 --- a/doc/api_review/core/keyNextMeta.md +++ b/doc/api_review/core/keyNextMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -const Key *keyNextMeta(Key *key) - +`const Key *keyNextMeta(Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ const Key *keyNextMeta(Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ const Key *keyNextMeta(Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ const Key *keyNextMeta(Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ const Key *keyNextMeta(Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyRewindMeta.md b/doc/api_review/core/keyRewindMeta.md index ea8fc5f936d..fbe49ef85ff 100644 --- a/doc/api_review/core/keyRewindMeta.md +++ b/doc/api_review/core/keyRewindMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int keyRewindMeta(Key *key) - +`int keyRewindMeta(Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int keyRewindMeta(Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int keyRewindMeta(Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int keyRewindMeta(Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int keyRewindMeta(Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keySetBaseName.md b/doc/api_review/core/keySetBaseName.md index 48dd0e0d8d8..fe33a397b36 100644 --- a/doc/api_review/core/keySetBaseName.md +++ b/doc/api_review/core/keySetBaseName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keySetBaseName(Key *key,const char *baseName) - +`ssize_t keySetBaseName(Key *key,const char *baseName)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keySetBaseName(Key *key,const char *baseName) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keySetBaseName(Key *key,const char *baseName) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keySetBaseName(Key *key,const char *baseName) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keySetBaseName(Key *key,const char *baseName) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keySetBinary.md b/doc/api_review/core/keySetBinary.md index e001c0437f3..c5092c57854 100644 --- a/doc/api_review/core/keySetBinary.md +++ b/doc/api_review/core/keySetBinary.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) - +`ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keySetMeta.md b/doc/api_review/core/keySetMeta.md index 38e21d07f20..c78aaa799db 100644 --- a/doc/api_review/core/keySetMeta.md +++ b/doc/api_review/core/keySetMeta.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) - +`ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keySetMeta(Key *key, const char* metaName,const char *newMetaString) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keySetName.md b/doc/api_review/core/keySetName.md index 1b4266666c9..84dd7a54588 100644 --- a/doc/api_review/core/keySetName.md +++ b/doc/api_review/core/keySetName.md @@ -1,89 +1,101 @@ # keySetName -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 -- moderator = Stefan Hanreich - +- start = 2021-02-14 03:30 +- end = 2021-02-14 03:50 +- reviewer = Stefan Hanreich ## Signature -ssize_t keySetName(Key *key, const char *newname) - +`ssize_t keySetName(Key *key, const char *newname)` ## Checklist #### Doxygen - -- [ ] First line explains briefly what the function does -- [ ] `@see` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +(bullet points are in order of appearance) + +- [x] First line explains briefly what the function does +- [ ] Simple example or snippet how to use the function + - [ ] add +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` + - [ ] @pre newName must be a valid name + - [ ] @pre must not be a read-only key + - [ ] @pre must not have been inserted before +- [ ] `@post` + - [ ] @post Key has (possibly modified) newName as name +- [ ] `@invariant` + - [ ] add +- [x] `@param` for every parameter +- [ ] `@return` / `@retval` + - [ ] add `@retval` -1 if key is read-only +- [ ] `@since` + - [ ] add +- [x] `@ingroup` +- [ ] `@see` + - [ ] add `keySetNameSpace()` ### Naming -- [ ] Abbreviations used in function names must be defined in the +- [x] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible -- [ ] Function parameters should use enum types instead of boolean types +- [x] Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` + - [ ] might be possible to make it `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [ ] Order of signatures in kdb.h.in is the same as Doxygen + - [ ] swapped with functions for unescaped +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] behaviour on invalid names ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - +- [ ] Function code is fully covered by tests + - [ ] test_bit "CANNOT" fail, so might not be necessary to cover this + for now should be made more resistant to future changes +- [ ] All possible error states are covered by tests + - [ ] test read-only keys +- All possible enum values are covered by tests +- [ ] No inconsistencies between tests and documentation + - [ ] https://github.com/ElektraInitiative/libelektra/blob/master/tests/abi/testabi_key.c#L357 + checks for -1 if null pointer is provided + documentation says 0 will be returned + - [ ] Documentation says name will be `""` after an invalid name + Tests show that name stays unchanged + https://github.com/ElektraInitiative/libelektra/blob/master/tests/abi/testabi_key.c#L601 + - [ ] Documentations should include stripping trailing `/` ## Summary diff --git a/doc/api_review/core/keySetNamespace.md b/doc/api_review/core/keySetNamespace.md index 176e53c661f..9f3e7b53458 100644 --- a/doc/api_review/core/keySetNamespace.md +++ b/doc/api_review/core/keySetNamespace.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keySetNamespace(Key * key, elektraNamespace ns) - +`ssize_t keySetNamespace(Key * key, elektraNamespace ns)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keySetNamespace(Key * key, elektraNamespace ns) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keySetNamespace(Key * key, elektraNamespace ns) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keySetNamespace(Key * key, elektraNamespace ns) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keySetNamespace(Key * key, elektraNamespace ns) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index cd15e2203a1..c3a3bee5a30 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t keySetString(Key *key, const char *newString) - +`ssize_t keySetString(Key *key, const char *newString)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t keySetString(Key *key, const char *newString) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t keySetString(Key *key, const char *newString) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t keySetString(Key *key, const char *newString) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t keySetString(Key *key, const char *newString) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyString.md b/doc/api_review/core/keyString.md index b539396529c..50271de226a 100644 --- a/doc/api_review/core/keyString.md +++ b/doc/api_review/core/keyString.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -const char *keyString(const Key *key) - +`const char *keyString(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ const char *keyString(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ const char *keyString(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ const char *keyString(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ const char *keyString(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyUnescapedName.md b/doc/api_review/core/keyUnescapedName.md index 032813dde7d..37961a63de2 100644 --- a/doc/api_review/core/keyUnescapedName.md +++ b/doc/api_review/core/keyUnescapedName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -const void *keyUnescapedName(const Key *key) - +`const void *keyUnescapedName(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ const void *keyUnescapedName(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ const void *keyUnescapedName(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ const void *keyUnescapedName(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ const void *keyUnescapedName(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyVNew.md b/doc/api_review/core/keyVNew.md index 717715e987f..95e9230d48a 100644 --- a/doc/api_review/core/keyVNew.md +++ b/doc/api_review/core/keyVNew.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *keyVNew(const char *keyname, va_list ap) - +`Key *keyVNew(const char *keyname, va_list ap)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *keyVNew(const char *keyname, va_list ap) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *keyVNew(const char *keyname, va_list ap) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *keyVNew(const char *keyname, va_list ap) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *keyVNew(const char *keyname, va_list ap) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/keyValue.md b/doc/api_review/core/keyValue.md index d1f6b0548e2..d55dcf56c43 100644 --- a/doc/api_review/core/keyValue.md +++ b/doc/api_review/core/keyValue.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -const void *keyValue(const Key *key) - +`const void *keyValue(const Key *key)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ const void *keyValue(const Key *key) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ const void *keyValue(const Key *key) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ const void *keyValue(const Key *key) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ const void *keyValue(const Key *key) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksAppend.md b/doc/api_review/core/ksAppend.md index 193ff6c73fc..edee948e046 100644 --- a/doc/api_review/core/ksAppend.md +++ b/doc/api_review/core/ksAppend.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) - +`ssize_t ksAppend(KeySet *ks, const KeySet *toAppend)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t ksAppend(KeySet *ks, const KeySet *toAppend) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksAppendKey.md b/doc/api_review/core/ksAppendKey.md index 5efa8ab2a26..f584df2bcb2 100644 --- a/doc/api_review/core/ksAppendKey.md +++ b/doc/api_review/core/ksAppendKey.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t ksAppendKey(KeySet *ks, Key *toAppend) - +`ssize_t ksAppendKey(KeySet *ks, Key *toAppend)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t ksAppendKey(KeySet *ks, Key *toAppend) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t ksAppendKey(KeySet *ks, Key *toAppend) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t ksAppendKey(KeySet *ks, Key *toAppend) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t ksAppendKey(KeySet *ks, Key *toAppend) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksAtCursor.md b/doc/api_review/core/ksAtCursor.md index 8487f7c392c..ed0f58716ea 100644 --- a/doc/api_review/core/ksAtCursor.md +++ b/doc/api_review/core/ksAtCursor.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksAtCursor(KeySet *ks, elektraCursor cursor) - +`Key *ksAtCursor(KeySet *ks, elektraCursor cursor)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksAtCursor(KeySet *ks, elektraCursor cursor) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksAtCursor(KeySet *ks, elektraCursor cursor) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksAtCursor(KeySet *ks, elektraCursor cursor) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksAtCursor(KeySet *ks, elektraCursor cursor) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksClear.md b/doc/api_review/core/ksClear.md index b09b5a2a163..57eca858fe4 100644 --- a/doc/api_review/core/ksClear.md +++ b/doc/api_review/core/ksClear.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int ksClear(KeySet *ks) - +`int ksClear(KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int ksClear(KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int ksClear(KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int ksClear(KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int ksClear(KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksCopy.md b/doc/api_review/core/ksCopy.md index 4feed74f372..02ed80e0bfd 100644 --- a/doc/api_review/core/ksCopy.md +++ b/doc/api_review/core/ksCopy.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int ksCopy(KeySet *dest, const KeySet *source) - +`int ksCopy(KeySet *dest, const KeySet *source)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int ksCopy(KeySet *dest, const KeySet *source) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int ksCopy(KeySet *dest, const KeySet *source) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int ksCopy(KeySet *dest, const KeySet *source) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int ksCopy(KeySet *dest, const KeySet *source) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksCurrent.md b/doc/api_review/core/ksCurrent.md index 39fade6468f..da0821bedc3 100644 --- a/doc/api_review/core/ksCurrent.md +++ b/doc/api_review/core/ksCurrent.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksCurrent(const KeySet *ks) - +`Key *ksCurrent(const KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksCurrent(const KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksCurrent(const KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksCurrent(const KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksCurrent(const KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksCut.md b/doc/api_review/core/ksCut.md index 72fc9b253a7..2b593b1924d 100644 --- a/doc/api_review/core/ksCut.md +++ b/doc/api_review/core/ksCut.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -KeySet *ksCut(KeySet *ks, const Key *cutpoint) - +`KeySet *ksCut(KeySet *ks, const Key *cutpoint)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ KeySet *ksCut(KeySet *ks, const Key *cutpoint) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ KeySet *ksCut(KeySet *ks, const Key *cutpoint) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ KeySet *ksCut(KeySet *ks, const Key *cutpoint) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ KeySet *ksCut(KeySet *ks, const Key *cutpoint) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksDel.md b/doc/api_review/core/ksDel.md index d09bccff8d3..6f1081ca99c 100644 --- a/doc/api_review/core/ksDel.md +++ b/doc/api_review/core/ksDel.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int ksDel(KeySet *ks) - +`int ksDel(KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int ksDel(KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int ksDel(KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int ksDel(KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int ksDel(KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksDup.md b/doc/api_review/core/ksDup.md index f045bc225be..df7c3241459 100644 --- a/doc/api_review/core/ksDup.md +++ b/doc/api_review/core/ksDup.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -KeySet *ksDup(const KeySet * source) - +`KeySet *ksDup(const KeySet * source)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ KeySet *ksDup(const KeySet * source) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ KeySet *ksDup(const KeySet * source) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ KeySet *ksDup(const KeySet * source) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ KeySet *ksDup(const KeySet * source) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksGetCursor.md b/doc/api_review/core/ksGetCursor.md index 6358d8648c9..2a6627aab2a 100644 --- a/doc/api_review/core/ksGetCursor.md +++ b/doc/api_review/core/ksGetCursor.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -elektraCursor ksGetCursor(const KeySet *ks) - +`elektraCursor ksGetCursor(const KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ elektraCursor ksGetCursor(const KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ elektraCursor ksGetCursor(const KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ elektraCursor ksGetCursor(const KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ elektraCursor ksGetCursor(const KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksGetSize.md b/doc/api_review/core/ksGetSize.md index c5ec12efae9..cba5db3667c 100644 --- a/doc/api_review/core/ksGetSize.md +++ b/doc/api_review/core/ksGetSize.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -ssize_t ksGetSize(const KeySet *ks) - +`ssize_t ksGetSize(const KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ ssize_t ksGetSize(const KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ ssize_t ksGetSize(const KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ ssize_t ksGetSize(const KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ ssize_t ksGetSize(const KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksHead.md b/doc/api_review/core/ksHead.md index e23f3b8ee71..d9f2330a1c1 100644 --- a/doc/api_review/core/ksHead.md +++ b/doc/api_review/core/ksHead.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksHead(const KeySet *ks) - +`Key *ksHead(const KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksHead(const KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksHead(const KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksHead(const KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksHead(const KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksLookup.md b/doc/api_review/core/ksLookup.md index 09753b6ab3f..691c353ccde 100644 --- a/doc/api_review/core/ksLookup.md +++ b/doc/api_review/core/ksLookup.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) - +`Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksLookup(KeySet *ks, Key *k, elektraLookupFlags options) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksLookupByName.md b/doc/api_review/core/ksLookupByName.md index 9e9555432b5..56274dbc159 100644 --- a/doc/api_review/core/ksLookupByName.md +++ b/doc/api_review/core/ksLookupByName.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) - +`Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksNeedSync.md b/doc/api_review/core/ksNeedSync.md index 39cbf567221..02a79417be4 100644 --- a/doc/api_review/core/ksNeedSync.md +++ b/doc/api_review/core/ksNeedSync.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int ksNeedSync(const KeySet *ks) - +`int ksNeedSync(const KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int ksNeedSync(const KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int ksNeedSync(const KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int ksNeedSync(const KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int ksNeedSync(const KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksNew.md b/doc/api_review/core/ksNew.md index 6e2b1916798..d1a7d95593b 100644 --- a/doc/api_review/core/ksNew.md +++ b/doc/api_review/core/ksNew.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL - +`KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ KeySet *ksNew(size_t alloc, ...) ELEKTRA_SENTINEL - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksNext.md b/doc/api_review/core/ksNext.md index 385460feaed..ee52b37f73a 100644 --- a/doc/api_review/core/ksNext.md +++ b/doc/api_review/core/ksNext.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksNext(KeySet *ks) - +`Key *ksNext(KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksNext(KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksNext(KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksNext(KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksNext(KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksPop.md b/doc/api_review/core/ksPop.md index 3de4db1c47a..81f2a406527 100644 --- a/doc/api_review/core/ksPop.md +++ b/doc/api_review/core/ksPop.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksPop(KeySet *ks) - +`Key *ksPop(KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksPop(KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksPop(KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksPop(KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksPop(KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksRewind.md b/doc/api_review/core/ksRewind.md index 408931e50b2..8ab8f931ba8 100644 --- a/doc/api_review/core/ksRewind.md +++ b/doc/api_review/core/ksRewind.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int ksRewind(KeySet *ks) - +`int ksRewind(KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int ksRewind(KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int ksRewind(KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int ksRewind(KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int ksRewind(KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksSetCursor.md b/doc/api_review/core/ksSetCursor.md index 8f901773504..f8e6f216336 100644 --- a/doc/api_review/core/ksSetCursor.md +++ b/doc/api_review/core/ksSetCursor.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -int ksSetCursor(KeySet *ks, elektraCursor cursor) - +`int ksSetCursor(KeySet *ks, elektraCursor cursor)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ int ksSetCursor(KeySet *ks, elektraCursor cursor) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ int ksSetCursor(KeySet *ks, elektraCursor cursor) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ int ksSetCursor(KeySet *ks, elektraCursor cursor) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ int ksSetCursor(KeySet *ks, elektraCursor cursor) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksTail.md b/doc/api_review/core/ksTail.md index c9c6fae16ba..8924ee4deaf 100644 --- a/doc/api_review/core/ksTail.md +++ b/doc/api_review/core/ksTail.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -Key *ksTail(const KeySet *ks) - +`Key *ksTail(const KeySet *ks)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ Key *ksTail(const KeySet *ks) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ Key *ksTail(const KeySet *ks) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ Key *ksTail(const KeySet *ks) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ Key *ksTail(const KeySet *ks) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/doc/api_review/core/ksVNew.md b/doc/api_review/core/ksVNew.md index fe784cfddff..de966a94c8d 100644 --- a/doc/api_review/core/ksVNew.md +++ b/doc/api_review/core/ksVNew.md @@ -4,34 +4,27 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature -KeySet *ksVNew(size_t alloc, va_list ap) - +`KeySet *ksVNew(size_t alloc, va_list ap)` ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -45,6 +38,7 @@ KeySet *ksVNew(size_t alloc, va_list ap) - [ ] Parameter names should be clear and unambiguous ### Compatibility +(only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes @@ -53,8 +47,6 @@ KeySet *ksVNew(size_t alloc, va_list ap) ### Parameter & Return Types -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible - [ ] Function parameters should use enum types instead of boolean types wherever sensible - [ ] Wherever possible, function parameters should be `const` @@ -65,7 +57,7 @@ KeySet *ksVNew(size_t alloc, va_list ap) - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +75,5 @@ KeySet *ksVNew(size_t alloc, va_list ap) - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/scripts/api_review/generate_review_files.py b/scripts/api_review/generate_review_files.py index 0089086a016..48c8ce6ff2e 100644 --- a/scripts/api_review/generate_review_files.py +++ b/scripts/api_review/generate_review_files.py @@ -38,7 +38,7 @@ def is_folder(path): '--template-path', help='Specify the path for the template', type=is_file, - default='template.md' + default='template.c.md' ) parser.add_argument( @@ -46,7 +46,7 @@ def is_folder(path): '--methods-path', help='Specify the path for the method list', type=is_file, - default='methods.txt' + default='methods.c.txt' ) args = parser.parse_args() diff --git a/scripts/api_review/methods.txt b/scripts/api_review/methods.c.txt similarity index 100% rename from scripts/api_review/methods.txt rename to scripts/api_review/methods.c.txt diff --git a/scripts/api_review/template.c.md b/scripts/api_review/template.c.md new file mode 100644 index 00000000000..5fb8cf70813 --- /dev/null +++ b/scripts/api_review/template.c.md @@ -0,0 +1,79 @@ +# {name} + +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- moderator = Stefan Hanreich + +## Signature + +`{signature}` + +## Checklist + +#### Doxygen +(bullet points are in order of appearance) + +- [ ] First line explains briefly what the function does +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] `@see` + +### Naming + +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Parameter names should be clear and unambiguous + +### Compatibility +(only in PRs) + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Function parameters should use enum types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Function name has the appropriate prefix +- [ ] Order of signatures in kdb.h.in is the same as Doxygen +- [ ] No functions with similar purpose exist + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible + +### Extensibility + +- [ ] Function is easily extensible, e.g., with flags +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Function code is fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible enum values are covered by tests +- [ ] No inconsistencies between tests and documentation + +## Summary diff --git a/scripts/api_review/template.md b/scripts/api_review/template.java.md similarity index 80% rename from scripts/api_review/template.md rename to scripts/api_review/template.java.md index 3851af886f6..f67630ace7c 100644 --- a/scripts/api_review/template.md +++ b/scripts/api_review/template.java.md @@ -13,25 +13,21 @@ ## Checklist #### Doxygen +(bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] `@see` +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` +- [ ] `@throws` - [ ] `@since` - [ ] `@ingroup` -- [ ] `@retval` -- [ ] Good example or snippet how to use the function -- [ ] Simple examples go first -- [ ] Precondition -- [ ] Postcondition -- [ ] Invariant -- [ ] `@param` for every parameter - -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Valid flags are documented +- [ ] `@see` ### Naming @@ -65,7 +61,6 @@ - [ ] Functions should do exactly one thing - [ ] Function name has the appropriate prefix -- [ ] Signature in kdb.h.in has same order as Doxygen docu - [ ] No functions with similar purpose exist ### Memory Management @@ -83,7 +78,5 @@ - [ ] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation -- [ ] Functions should have no side effects (idempotency) - ## Summary diff --git a/scripts/api_review/template.rs.md b/scripts/api_review/template.rs.md new file mode 100644 index 00000000000..71e4c40062e --- /dev/null +++ b/scripts/api_review/template.rs.md @@ -0,0 +1,81 @@ +# {name} + +- start = 2021-01-23 18:10 +- end = 2021-01-23 18:10 +- moderator = Stefan Hanreich + + +## Signature + +{signature} + + +## Checklist + +#### Doxygen +(bullet points are in order of appearance) + +- [ ] First line explains briefly what the function does +- [ ] Simple example or snippet how to use the function +- [ ] Longer description of function containing common use cases +- [ ] Description of functions reads nicely +- [ ] `@pre` +- [ ] `@post` +- [ ] `@invariant` +- [ ] `@param` for every parameter +- [ ] `@return` / `@retval` +- [ ] `@since` +- [ ] `@ingroup` +- [ ] `@see` + +### Naming + +- [ ] Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous +- [ ] Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short +- [ ] Parameter names should be clear and unambiguous + +### Compatibility + +- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) + +### Parameter & Return Types + +- [ ] Functions should return the most specific type possible +- [ ] Functions should require the most general type possible +- [ ] Function parameters should use enum types instead of boolean types + wherever sensible +- [ ] Wherever possible, function parameters should be `const` +- [ ] Wherever possible, return types should be `const` +- [ ] Functions should have the least amount of parameters feasible + +### Structural Clarity + +- [ ] Functions should do exactly one thing +- [ ] Function name has the appropriate prefix +- [ ] No functions with similar purpose exist + +### Memory Management + +- [ ] Memory Management should be handled by the function wherever possible + +### Extensibility + +- [ ] Function is easily extensible, e.g., with flags +- [ ] Documentation does not impose limits, that would hinder further extensions + +### Tests + +- [ ] Function code is fully covered by tests +- [ ] All possible error states are covered by tests +- [ ] All possible enum values are covered by tests +- [ ] No inconsistencies between tests and documentation + +## Summary From 2053ea97388a0e1d94dddfd4c1589730a3838428 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Sat, 20 Feb 2021 01:32:02 +0100 Subject: [PATCH 12/29] docs: reformat-markdown applied --- doc/DESIGN.md | 2 - doc/api_review/README.md | 24 +++++---- doc/api_review/core/kdbClose.md | 2 + doc/api_review/core/kdbEnsure.md | 2 + doc/api_review/core/kdbGet.md | 2 + doc/api_review/core/kdbOpen.md | 2 + doc/api_review/core/kdbSet.md | 2 + doc/api_review/core/keyAddBaseName.md | 2 + doc/api_review/core/keyAddName.md | 2 + doc/api_review/core/keyBaseName.md | 2 + doc/api_review/core/keyClear.md | 2 + doc/api_review/core/keyCmp.md | 2 + doc/api_review/core/keyCopy.md | 2 + doc/api_review/core/keyCopyAllMeta.md | 2 + doc/api_review/core/keyCopyMeta.md | 2 + doc/api_review/core/keyCurrentMeta.md | 2 + doc/api_review/core/keyDecRef.md | 2 + doc/api_review/core/keyDel.md | 24 +++++---- doc/api_review/core/keyDup.md | 2 + doc/api_review/core/keyGetBaseName.md | 2 + doc/api_review/core/keyGetBaseNameSize.md | 2 + doc/api_review/core/keyGetBinary.md | 2 + doc/api_review/core/keyGetMeta.md | 2 + doc/api_review/core/keyGetName.md | 2 + doc/api_review/core/keyGetNameSize.md | 2 + doc/api_review/core/keyGetNamespace.md | 2 + doc/api_review/core/keyGetRef.md | 2 + doc/api_review/core/keyGetString.md | 2 + .../core/keyGetUnescapedNameSize.md | 2 + doc/api_review/core/keyGetValueSize.md | 2 + doc/api_review/core/keyIncRef.md | 2 + doc/api_review/core/keyIsBelow.md | 2 + doc/api_review/core/keyIsBelowOrSame.md | 2 + doc/api_review/core/keyIsBinary.md | 2 + doc/api_review/core/keyIsDirectlyBelow.md | 2 + doc/api_review/core/keyIsLocked.md | 2 + doc/api_review/core/keyIsString.md | 2 + doc/api_review/core/keyLock.md | 2 + doc/api_review/core/keyMeta.md | 2 + doc/api_review/core/keyName.md | 26 +++++----- doc/api_review/core/keyNeedSync.md | 2 + doc/api_review/core/keyNew.md | 40 +++++++-------- doc/api_review/core/keyNextMeta.md | 2 + doc/api_review/core/keyRewindMeta.md | 2 + doc/api_review/core/keySetBaseName.md | 2 + doc/api_review/core/keySetBinary.md | 2 + doc/api_review/core/keySetMeta.md | 2 + doc/api_review/core/keySetName.md | 50 ++++++++++--------- doc/api_review/core/keySetNamespace.md | 2 + doc/api_review/core/keySetString.md | 2 + doc/api_review/core/keyString.md | 2 + doc/api_review/core/keyUnescapedName.md | 2 + doc/api_review/core/keyVNew.md | 2 + doc/api_review/core/keyValue.md | 2 + doc/api_review/core/ksAppend.md | 2 + doc/api_review/core/ksAppendKey.md | 2 + doc/api_review/core/ksAtCursor.md | 2 + doc/api_review/core/ksClear.md | 2 + doc/api_review/core/ksCopy.md | 2 + doc/api_review/core/ksCurrent.md | 2 + doc/api_review/core/ksCut.md | 2 + doc/api_review/core/ksDel.md | 2 + doc/api_review/core/ksDup.md | 2 + doc/api_review/core/ksGetCursor.md | 2 + doc/api_review/core/ksGetSize.md | 2 + doc/api_review/core/ksHead.md | 2 + doc/api_review/core/ksLookup.md | 2 + doc/api_review/core/ksLookupByName.md | 2 + doc/api_review/core/ksNeedSync.md | 2 + doc/api_review/core/ksNew.md | 2 + doc/api_review/core/ksNext.md | 2 + doc/api_review/core/ksPop.md | 2 + doc/api_review/core/ksRewind.md | 2 + doc/api_review/core/ksSetCursor.md | 2 + doc/api_review/core/ksTail.md | 2 + doc/api_review/core/ksVNew.md | 2 + scripts/api_review/README.md | 3 +- scripts/api_review/template.c.md | 2 + scripts/api_review/template.java.md | 3 +- scripts/api_review/template.rs.md | 3 +- 80 files changed, 231 insertions(+), 86 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index c0a107f2a2d..23bdb833792 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -291,7 +291,6 @@ On potential changes of the API/ABI as detected by please make sure the API has been reviewed according to the following 2 checklists: - ## Checklist for overall API ### Consistency @@ -314,7 +313,6 @@ following 2 checklists: - [ ] New API is easily extensible with additional functionality - [ ] Components only depend on each other if needed - ## Checklist for each function ### Documentation diff --git a/doc/api_review/README.md b/doc/api_review/README.md index b3823636db7..7e257c5121e 100644 --- a/doc/api_review/README.md +++ b/doc/api_review/README.md @@ -1,25 +1,27 @@ # Elektra API Review + This folder contains all API design reviews conducted on the Elektra library. Below you can find a short description of the review process. ## Review Process -This review is performed for each function separately. Each function should be -evaluated according to the checklist. The reviewer judges for every bullet -point, whether the function does / does not fulfill the bullet point. For -every unfulfilled point a short explanation has to be given why the reviewer -thinks the function does not fulfill the respective bullet point. This is done -simply by providing a short description of the issue below the respective -bullet point. After the review has been completed, the reviewer creates an + +This review is performed for each function separately. Each function should be +evaluated according to the checklist. The reviewer judges for every bullet +point, whether the function does / does not fulfill the bullet point. For +every unfulfilled point a short explanation has to be given why the reviewer +thinks the function does not fulfill the respective bullet point. This is done +simply by providing a short description of the issue below the respective +bullet point. After the review has been completed, the reviewer creates an issue for every unfulfilled bullet point so it can be fixed by the Elektra team. ## Checklist Legend - [ ] not fulfilled - This is the reason for why its is not fulfilled + This is the reason for why its is not fulfilled - [x] fulfilled - not applicable - ## Templates -The template and the script for generating review files based on that template -can be found [here](/scripts/api_review/README.md) \ No newline at end of file + +The template and the script for generating review files based on that template +can be found [here](/scripts/api_review/README.md) diff --git a/doc/api_review/core/kdbClose.md b/doc/api_review/core/kdbClose.md index ae4b9e0acb6..289bca96823 100644 --- a/doc/api_review/core/kdbClose.md +++ b/doc/api_review/core/kdbClose.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/kdbEnsure.md b/doc/api_review/core/kdbEnsure.md index fbaa786d946..9f0cbed068c 100644 --- a/doc/api_review/core/kdbEnsure.md +++ b/doc/api_review/core/kdbEnsure.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/kdbGet.md b/doc/api_review/core/kdbGet.md index af8e8a8df50..41f7a2818ed 100644 --- a/doc/api_review/core/kdbGet.md +++ b/doc/api_review/core/kdbGet.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/kdbOpen.md b/doc/api_review/core/kdbOpen.md index 8108bc892b6..ef5331c910d 100644 --- a/doc/api_review/core/kdbOpen.md +++ b/doc/api_review/core/kdbOpen.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/kdbSet.md b/doc/api_review/core/kdbSet.md index 3682686cdec..4dcdb646ac1 100644 --- a/doc/api_review/core/kdbSet.md +++ b/doc/api_review/core/kdbSet.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyAddBaseName.md b/doc/api_review/core/keyAddBaseName.md index 13159ded53a..193c8141d31 100644 --- a/doc/api_review/core/keyAddBaseName.md +++ b/doc/api_review/core/keyAddBaseName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyAddName.md b/doc/api_review/core/keyAddName.md index 5aab1f2154e..24f64015af3 100644 --- a/doc/api_review/core/keyAddName.md +++ b/doc/api_review/core/keyAddName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyBaseName.md b/doc/api_review/core/keyBaseName.md index 3113867e1bd..6ab89df2292 100644 --- a/doc/api_review/core/keyBaseName.md +++ b/doc/api_review/core/keyBaseName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index e0b3ae3efad..8845285a761 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyCmp.md b/doc/api_review/core/keyCmp.md index 9ddbe69beaf..f0bb0f00a8e 100644 --- a/doc/api_review/core/keyCmp.md +++ b/doc/api_review/core/keyCmp.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyCopy.md b/doc/api_review/core/keyCopy.md index 0b5d51fc51a..2c5c88fd78e 100644 --- a/doc/api_review/core/keyCopy.md +++ b/doc/api_review/core/keyCopy.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyCopyAllMeta.md b/doc/api_review/core/keyCopyAllMeta.md index 167f5298aca..2f8b04434b7 100644 --- a/doc/api_review/core/keyCopyAllMeta.md +++ b/doc/api_review/core/keyCopyAllMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyCopyMeta.md b/doc/api_review/core/keyCopyMeta.md index 23ba7e855cb..c747a5b8406 100644 --- a/doc/api_review/core/keyCopyMeta.md +++ b/doc/api_review/core/keyCopyMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyCurrentMeta.md b/doc/api_review/core/keyCurrentMeta.md index b281eaea769..d5107ba6388 100644 --- a/doc/api_review/core/keyCurrentMeta.md +++ b/doc/api_review/core/keyCurrentMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index 3de96fcfc1d..df2cfc8f8b4 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyDel.md b/doc/api_review/core/keyDel.md index 23f405aca94..e8bb0ebfeeb 100644 --- a/doc/api_review/core/keyDel.md +++ b/doc/api_review/core/keyDel.md @@ -11,24 +11,25 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function - - [ ] add example + - [ ] add example - [x] Longer description of function containing common use cases - [x] Description of functions reads nicely - [ ] `@pre` - - [ ] @pre Key must not be null + - [ ] @pre Key must not be null - [ ] `@post` - - [ ] @post Key memory has been freed + - [ ] @post Key memory has been freed - [ ] `@invariant - - [ ] add (tbd) + - [ ] add (tbd) - [x] `@param` for every parameter - [ ] `@return` / `@retval` - - [ ] `0` when the key was freed and no references are held in keysets + - [ ] `0` when the key was freed and no references are held in keysets - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [x] `@see` @@ -44,12 +45,13 @@ - [x] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types @@ -57,7 +59,7 @@ wherever sensible - [x] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` - - [ ] could maybe change this to const + - [ ] could maybe change this to const - [x] Functions should have the least amount of parameters feasible ### Structural Clarity @@ -65,7 +67,7 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen - - [ ] swap keyClear and keyDel + - [ ] swap keyClear and keyDel - [x] No functions with similar purpose exist ### Memory Management @@ -76,7 +78,7 @@ - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] TBD cannot change behaviour of referenced keys + - [ ] TBD cannot change behaviour of referenced keys ### Tests diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index 639e56f954b..ce96901b37e 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetBaseName.md b/doc/api_review/core/keyGetBaseName.md index 3ae63635e81..03eb6c1f48a 100644 --- a/doc/api_review/core/keyGetBaseName.md +++ b/doc/api_review/core/keyGetBaseName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetBaseNameSize.md b/doc/api_review/core/keyGetBaseNameSize.md index 1ed61816578..c34e077e213 100644 --- a/doc/api_review/core/keyGetBaseNameSize.md +++ b/doc/api_review/core/keyGetBaseNameSize.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetBinary.md b/doc/api_review/core/keyGetBinary.md index 879fe374de5..d2ccc83f9ee 100644 --- a/doc/api_review/core/keyGetBinary.md +++ b/doc/api_review/core/keyGetBinary.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetMeta.md b/doc/api_review/core/keyGetMeta.md index c1d660a8560..e402848ce17 100644 --- a/doc/api_review/core/keyGetMeta.md +++ b/doc/api_review/core/keyGetMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index 6c94cabd426..00b2052c155 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md index 9a86c0ff0dd..a7e1b7c6af1 100644 --- a/doc/api_review/core/keyGetNameSize.md +++ b/doc/api_review/core/keyGetNameSize.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetNamespace.md b/doc/api_review/core/keyGetNamespace.md index 5b26d28d685..ea4cc7bdc5e 100644 --- a/doc/api_review/core/keyGetNamespace.md +++ b/doc/api_review/core/keyGetNamespace.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index 40b717c750f..4536f6acd11 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetString.md b/doc/api_review/core/keyGetString.md index 53c552cf42b..78302d60259 100644 --- a/doc/api_review/core/keyGetString.md +++ b/doc/api_review/core/keyGetString.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetUnescapedNameSize.md b/doc/api_review/core/keyGetUnescapedNameSize.md index 736cb132cde..fb053a53653 100644 --- a/doc/api_review/core/keyGetUnescapedNameSize.md +++ b/doc/api_review/core/keyGetUnescapedNameSize.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyGetValueSize.md b/doc/api_review/core/keyGetValueSize.md index f327d50fc28..7a6d841cc51 100644 --- a/doc/api_review/core/keyGetValueSize.md +++ b/doc/api_review/core/keyGetValueSize.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index a952c3b1794..3c0d0875ecb 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyIsBelow.md b/doc/api_review/core/keyIsBelow.md index 3930d787d11..cf21897f971 100644 --- a/doc/api_review/core/keyIsBelow.md +++ b/doc/api_review/core/keyIsBelow.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyIsBelowOrSame.md b/doc/api_review/core/keyIsBelowOrSame.md index 0b1a10241e3..7db7d73e60b 100644 --- a/doc/api_review/core/keyIsBelowOrSame.md +++ b/doc/api_review/core/keyIsBelowOrSame.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyIsBinary.md b/doc/api_review/core/keyIsBinary.md index 87f86566b41..aff764a4914 100644 --- a/doc/api_review/core/keyIsBinary.md +++ b/doc/api_review/core/keyIsBinary.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyIsDirectlyBelow.md b/doc/api_review/core/keyIsDirectlyBelow.md index 12bc1270b23..a1dc87f1566 100644 --- a/doc/api_review/core/keyIsDirectlyBelow.md +++ b/doc/api_review/core/keyIsDirectlyBelow.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index badb03820ed..ea9c5e83f83 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyIsString.md b/doc/api_review/core/keyIsString.md index 158d0cdae6c..f763782ce2d 100644 --- a/doc/api_review/core/keyIsString.md +++ b/doc/api_review/core/keyIsString.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index 1992ab6d0f4..a08089255b2 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyMeta.md b/doc/api_review/core/keyMeta.md index 43503fe6d5e..32d75bbb9e5 100644 --- a/doc/api_review/core/keyMeta.md +++ b/doc/api_review/core/keyMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyName.md b/doc/api_review/core/keyName.md index 1e2dca8f611..361a68f39f8 100644 --- a/doc/api_review/core/keyName.md +++ b/doc/api_review/core/keyName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [x] First line explains briefly what the function does @@ -18,16 +19,16 @@ - [ ] Longer description of function containing common use cases - [ ] Description of functions reads nicely - [ ] `@pre` - - [ ] @pre key must be a valid key + - [ ] @pre key must be a valid key - [ ] `@post` - - [ ] @post Pointer to key that can change over time + - [ ] @post Pointer to key that can change over time - [ ] `@invariant` - - [ ] key name stays valid + - [ ] key name stays valid - [x] `@param` for every parameter - [ ] `@return` / `@retval` - - [ ] add default return value to `@retval` + - [ ] add default return value to `@retval` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [x] `@see` @@ -37,25 +38,26 @@ [Glossary](/doc/help/elektra-glossary.md) - [x] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous - - [ ] Function name might lead to confusions with `keyGetName()`, make - their intentions more clear in their names + - [ ] Function name might lead to confusions with `keyGetName()`, make + their intentions more clear in their names - [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [x] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types - Function parameters should use enum types instead of boolean types - wherever sensible + wherever sensible - [x] Wherever possible, function parameters should be `const` - [x] Wherever possible, return types should be `const` - [x] Functions should have the least amount of parameters feasible @@ -66,7 +68,7 @@ - [x] Function name has the appropriate prefix - [x] Order of signatures in kdb.h.in is the same as Doxygen - [x] No functions with similar purpose exist - - [ ] `keyUnescapedName` might be considered too similar + - [ ] `keyUnescapedName` might be considered too similar ### Memory Management @@ -81,7 +83,7 @@ - [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests - - [ ] empty keyName is not covered in tests + - [ ] empty keyName is not covered in tests - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyNeedSync.md b/doc/api_review/core/keyNeedSync.md index b18fdce04ae..20831fc08ff 100644 --- a/doc/api_review/core/keyNeedSync.md +++ b/doc/api_review/core/keyNeedSync.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyNew.md b/doc/api_review/core/keyNew.md index e7466b62875..4c348f9a1e4 100644 --- a/doc/api_review/core/keyNew.md +++ b/doc/api_review/core/keyNew.md @@ -11,24 +11,25 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [x] First line explains briefly what the function does - [x] Simple example or snippet how to use the function - [ ] Longer description of function containing common use cases - - [ ] is 0 a valid name? returns NULL if 0 is param + - [ ] is 0 a valid name? returns NULL if 0 is param - [x] Description of functions reads nicely - [ ] `@pre` - - [ ] @pre name must be a valid key name + - [ ] @pre name must be a valid key name - [ ] `@post` - - [ ] @post returns a valid key object + - [ ] @post returns a valid key object - [ ] `@invariant` - - [ ] add + - [ ] add - [ ] `@param` for every parameter - - [ ] add `@param` for `...` + - [ ] add `@param` for `...` - [x] `@return` / `@retval` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [x] `@see` @@ -44,12 +45,13 @@ - [x] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types @@ -62,7 +64,7 @@ ### Structural Clarity - [x] Functions should do exactly one thing - - it doesn't technically - but its a convenience function + - it doesn't technically - but its a convenience function - [x] Function name has the appropriate prefix - [x] Order of signatures in kdb.h.in is the same as Doxygen - [x] No functions with similar purpose exist @@ -75,24 +77,20 @@ - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] Docs say `Key *k = keyNew(0);` has same effect - as `Key *k =keyNew("", KEY_END);` + - [ ] Docs say `Key *k = keyNew(0);` has same effect + as `Key *k =keyNew("", KEY_END);` ### Tests - [x] Function code is fully covered by tests - [x] All possible error states are covered by tests - [ ] All possible enum values are covered by tests - - [ ] KEY_META - - [ ] KEY_FLAGS + - [ ] KEY_META + - [ ] KEY_FLAGS - [ ] No inconsistencies between tests and documentation - - [ ] Documentation says i can work with `Key *k =keyNew("", KEY_END);` - Tests say - ``` - k = keyNew ("", KEY_END); - succeed_if (k == NULL, "should be invalid"); - keyDel (k); - ``` - - [ ] same as above with `keyNew(0)` + - [ ] Documentation says i can work with `Key *k =keyNew("", KEY_END);` + Tests say + `k = keyNew ("", KEY_END); succeed_if (k == NULL, "should be invalid"); keyDel (k);` + - [ ] same as above with `keyNew(0)` ## Summary diff --git a/doc/api_review/core/keyNextMeta.md b/doc/api_review/core/keyNextMeta.md index 10e218b453b..2456ac73484 100644 --- a/doc/api_review/core/keyNextMeta.md +++ b/doc/api_review/core/keyNextMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyRewindMeta.md b/doc/api_review/core/keyRewindMeta.md index fbe49ef85ff..df9a88febd1 100644 --- a/doc/api_review/core/keyRewindMeta.md +++ b/doc/api_review/core/keyRewindMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keySetBaseName.md b/doc/api_review/core/keySetBaseName.md index fe33a397b36..5f154aceb5c 100644 --- a/doc/api_review/core/keySetBaseName.md +++ b/doc/api_review/core/keySetBaseName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keySetBinary.md b/doc/api_review/core/keySetBinary.md index c5092c57854..d4c45befd77 100644 --- a/doc/api_review/core/keySetBinary.md +++ b/doc/api_review/core/keySetBinary.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keySetMeta.md b/doc/api_review/core/keySetMeta.md index c78aaa799db..a60dd973fe8 100644 --- a/doc/api_review/core/keySetMeta.md +++ b/doc/api_review/core/keySetMeta.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keySetName.md b/doc/api_review/core/keySetName.md index 84dd7a54588..c3b172fbaac 100644 --- a/doc/api_review/core/keySetName.md +++ b/doc/api_review/core/keySetName.md @@ -11,29 +11,30 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function - - [ ] add + - [ ] add - [ ] Longer description of function containing common use cases - [ ] Description of functions reads nicely - [ ] `@pre` - - [ ] @pre newName must be a valid name - - [ ] @pre must not be a read-only key - - [ ] @pre must not have been inserted before + - [ ] @pre newName must be a valid name + - [ ] @pre must not be a read-only key + - [ ] @pre must not have been inserted before - [ ] `@post` - - [ ] @post Key has (possibly modified) newName as name + - [ ] @post Key has (possibly modified) newName as name - [ ] `@invariant` - - [ ] add + - [ ] add - [x] `@param` for every parameter - [ ] `@return` / `@retval` - - [ ] add `@retval` -1 if key is read-only + - [ ] add `@retval` -1 if key is read-only - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - [ ] add `keySetNameSpace()` + - [ ] add `keySetNameSpace()` ### Naming @@ -47,12 +48,13 @@ - [x] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types @@ -60,7 +62,7 @@ wherever sensible - [x] Wherever possible, function parameters should be `const` - [ ] Wherever possible, return types should be `const` - - [ ] might be possible to make it `const` + - [ ] might be possible to make it `const` - [x] Functions should have the least amount of parameters feasible ### Structural Clarity @@ -68,7 +70,7 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen - - [ ] swapped with functions for unescaped + - [ ] swapped with functions for unescaped - [x] No functions with similar purpose exist ### Memory Management @@ -79,23 +81,23 @@ - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] behaviour on invalid names + - [ ] behaviour on invalid names ### Tests - [ ] Function code is fully covered by tests - - [ ] test_bit "CANNOT" fail, so might not be necessary to cover this - for now should be made more resistant to future changes + - [ ] test_bit "CANNOT" fail, so might not be necessary to cover this + for now should be made more resistant to future changes - [ ] All possible error states are covered by tests - - [ ] test read-only keys + - [ ] test read-only keys - All possible enum values are covered by tests - [ ] No inconsistencies between tests and documentation - - [ ] https://github.com/ElektraInitiative/libelektra/blob/master/tests/abi/testabi_key.c#L357 - checks for -1 if null pointer is provided - documentation says 0 will be returned - - [ ] Documentation says name will be `""` after an invalid name - Tests show that name stays unchanged - https://github.com/ElektraInitiative/libelektra/blob/master/tests/abi/testabi_key.c#L601 - - [ ] Documentations should include stripping trailing `/` + - [ ] https://github.com/ElektraInitiative/libelektra/blob/master/tests/abi/testabi_key.c#L357 + checks for -1 if null pointer is provided + documentation says 0 will be returned + - [ ] Documentation says name will be `""` after an invalid name + Tests show that name stays unchanged + https://github.com/ElektraInitiative/libelektra/blob/master/tests/abi/testabi_key.c#L601 + - [ ] Documentations should include stripping trailing `/` ## Summary diff --git a/doc/api_review/core/keySetNamespace.md b/doc/api_review/core/keySetNamespace.md index 9f3e7b53458..7b9b1722882 100644 --- a/doc/api_review/core/keySetNamespace.md +++ b/doc/api_review/core/keySetNamespace.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index c3a3bee5a30..784fa5aaeb1 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyString.md b/doc/api_review/core/keyString.md index 50271de226a..8be71dc58f9 100644 --- a/doc/api_review/core/keyString.md +++ b/doc/api_review/core/keyString.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyUnescapedName.md b/doc/api_review/core/keyUnescapedName.md index 37961a63de2..043c799400c 100644 --- a/doc/api_review/core/keyUnescapedName.md +++ b/doc/api_review/core/keyUnescapedName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyVNew.md b/doc/api_review/core/keyVNew.md index 95e9230d48a..23cbbf62472 100644 --- a/doc/api_review/core/keyVNew.md +++ b/doc/api_review/core/keyVNew.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/keyValue.md b/doc/api_review/core/keyValue.md index d55dcf56c43..00e244687fc 100644 --- a/doc/api_review/core/keyValue.md +++ b/doc/api_review/core/keyValue.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksAppend.md b/doc/api_review/core/ksAppend.md index edee948e046..63c5f6c3471 100644 --- a/doc/api_review/core/ksAppend.md +++ b/doc/api_review/core/ksAppend.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksAppendKey.md b/doc/api_review/core/ksAppendKey.md index f584df2bcb2..b5e1a847a68 100644 --- a/doc/api_review/core/ksAppendKey.md +++ b/doc/api_review/core/ksAppendKey.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksAtCursor.md b/doc/api_review/core/ksAtCursor.md index ed0f58716ea..d7acdeb5752 100644 --- a/doc/api_review/core/ksAtCursor.md +++ b/doc/api_review/core/ksAtCursor.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksClear.md b/doc/api_review/core/ksClear.md index 57eca858fe4..045213764f7 100644 --- a/doc/api_review/core/ksClear.md +++ b/doc/api_review/core/ksClear.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksCopy.md b/doc/api_review/core/ksCopy.md index 02ed80e0bfd..3499d559d1b 100644 --- a/doc/api_review/core/ksCopy.md +++ b/doc/api_review/core/ksCopy.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksCurrent.md b/doc/api_review/core/ksCurrent.md index da0821bedc3..30ee70a4ccf 100644 --- a/doc/api_review/core/ksCurrent.md +++ b/doc/api_review/core/ksCurrent.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksCut.md b/doc/api_review/core/ksCut.md index 2b593b1924d..63bcff19b57 100644 --- a/doc/api_review/core/ksCut.md +++ b/doc/api_review/core/ksCut.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksDel.md b/doc/api_review/core/ksDel.md index 6f1081ca99c..70412cce9f6 100644 --- a/doc/api_review/core/ksDel.md +++ b/doc/api_review/core/ksDel.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksDup.md b/doc/api_review/core/ksDup.md index df7c3241459..757074ee945 100644 --- a/doc/api_review/core/ksDup.md +++ b/doc/api_review/core/ksDup.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksGetCursor.md b/doc/api_review/core/ksGetCursor.md index 2a6627aab2a..7e6e6a3ce26 100644 --- a/doc/api_review/core/ksGetCursor.md +++ b/doc/api_review/core/ksGetCursor.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksGetSize.md b/doc/api_review/core/ksGetSize.md index cba5db3667c..8cb08a3b84c 100644 --- a/doc/api_review/core/ksGetSize.md +++ b/doc/api_review/core/ksGetSize.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksHead.md b/doc/api_review/core/ksHead.md index d9f2330a1c1..64744c62833 100644 --- a/doc/api_review/core/ksHead.md +++ b/doc/api_review/core/ksHead.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksLookup.md b/doc/api_review/core/ksLookup.md index 691c353ccde..1c8fc81009a 100644 --- a/doc/api_review/core/ksLookup.md +++ b/doc/api_review/core/ksLookup.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksLookupByName.md b/doc/api_review/core/ksLookupByName.md index 56274dbc159..143b6ed15bc 100644 --- a/doc/api_review/core/ksLookupByName.md +++ b/doc/api_review/core/ksLookupByName.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksNeedSync.md b/doc/api_review/core/ksNeedSync.md index 02a79417be4..3b3a339b85c 100644 --- a/doc/api_review/core/ksNeedSync.md +++ b/doc/api_review/core/ksNeedSync.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksNew.md b/doc/api_review/core/ksNew.md index d1a7d95593b..907820b207f 100644 --- a/doc/api_review/core/ksNew.md +++ b/doc/api_review/core/ksNew.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksNext.md b/doc/api_review/core/ksNext.md index ee52b37f73a..c5d1b0782ef 100644 --- a/doc/api_review/core/ksNext.md +++ b/doc/api_review/core/ksNext.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksPop.md b/doc/api_review/core/ksPop.md index 81f2a406527..8407e736ee6 100644 --- a/doc/api_review/core/ksPop.md +++ b/doc/api_review/core/ksPop.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksRewind.md b/doc/api_review/core/ksRewind.md index 8ab8f931ba8..8e3bb92e7f1 100644 --- a/doc/api_review/core/ksRewind.md +++ b/doc/api_review/core/ksRewind.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksSetCursor.md b/doc/api_review/core/ksSetCursor.md index f8e6f216336..79d80a84089 100644 --- a/doc/api_review/core/ksSetCursor.md +++ b/doc/api_review/core/ksSetCursor.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksTail.md b/doc/api_review/core/ksTail.md index 8924ee4deaf..9e934b9c6fe 100644 --- a/doc/api_review/core/ksTail.md +++ b/doc/api_review/core/ksTail.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/doc/api_review/core/ksVNew.md b/doc/api_review/core/ksVNew.md index de966a94c8d..52fc9a19f66 100644 --- a/doc/api_review/core/ksVNew.md +++ b/doc/api_review/core/ksVNew.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/scripts/api_review/README.md b/scripts/api_review/README.md index 76c4ec7135a..6e35b1ab175 100644 --- a/scripts/api_review/README.md +++ b/scripts/api_review/README.md @@ -1,2 +1,3 @@ # Elektra API Review Template Script -This python script generates new review files from the given template. \ No newline at end of file + +This python script generates new review files from the given template. diff --git a/scripts/api_review/template.c.md b/scripts/api_review/template.c.md index 5fb8cf70813..2305e51fb70 100644 --- a/scripts/api_review/template.c.md +++ b/scripts/api_review/template.c.md @@ -11,6 +11,7 @@ ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does @@ -38,6 +39,7 @@ - [ ] Parameter names should be clear and unambiguous ### Compatibility + (only in PRs) - [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) diff --git a/scripts/api_review/template.java.md b/scripts/api_review/template.java.md index f67630ace7c..ca06eb867c6 100644 --- a/scripts/api_review/template.java.md +++ b/scripts/api_review/template.java.md @@ -4,15 +4,14 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature {signature} - ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does diff --git a/scripts/api_review/template.rs.md b/scripts/api_review/template.rs.md index 71e4c40062e..47b431b2ad1 100644 --- a/scripts/api_review/template.rs.md +++ b/scripts/api_review/template.rs.md @@ -4,15 +4,14 @@ - end = 2021-01-23 18:10 - moderator = Stefan Hanreich - ## Signature {signature} - ## Checklist #### Doxygen + (bullet points are in order of appearance) - [ ] First line explains briefly what the function does From e197e905ab521b3e43c4def53f5ed8272f3e8f24 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Sun, 21 Feb 2021 22:24:13 +0100 Subject: [PATCH 13/29] docs: review remaining functions in key module --- doc/api_review/core/keyClear.md | 65 +++++++++++++++++------------ doc/api_review/core/keyDecRef.md | 65 +++++++++++++++++------------ doc/api_review/core/keyDup.md | 66 +++++++++++++++++------------ doc/api_review/core/keyGetRef.md | 66 ++++++++++++++++------------- doc/api_review/core/keyIncRef.md | 67 +++++++++++++++++------------- doc/api_review/core/keyIsLocked.md | 63 +++++++++++++++++----------- doc/api_review/core/keyLock.md | 65 ++++++++++++++++++----------- 7 files changed, 273 insertions(+), 184 deletions(-) diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index 8845285a761..77a5724afb4 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -1,8 +1,8 @@ # keyClear -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 -- moderator = Stefan Hanreich +- start = 2021-01-23 18:40 +- end = 2021-01-23 19:00 +- reviewer = Stefan Hanreich ## Signature @@ -15,67 +15,80 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does -- [ ] Simple example or snippet how to use the function + - remove first line, second line could be improved a bit + (what is meant with internal data, exactly? is the name included?) +- [x] Simple example or snippet how to use the function - [ ] Longer description of function containing common use cases + - be more explicit which data is actually included - [ ] Description of functions reads nicely + - [ ] very short sentences - [ ] `@pre` + - [ ] @pre key is a valid key - [ ] `@post` + - [ ] @post key contains not internal data - [ ] `@invariant` -- [ ] `@param` for every parameter + - [ ] @invariant key stays a valid key +- [x] `@param` for every parameter - [ ] `@return` / `@retval` + - [ ] mark default case with `@return` - [ ] `@since` -- [ ] `@ingroup` + - [ ] add +- [x] `@ingroup` - [ ] `@see` + - [ ] maybe `keyDel()` ### Naming -- [ ] Abbreviations used in function names must be defined in the +- Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types +- Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen + - [ ] swap with `keyDel()` - [ ] No functions with similar purpose exist + - [ ] new keyCopy can also clear a key, maybe make `keyClear` an alias? ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility - [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] could add flags for clearing parts of the key like `keyCopy()` +- [x] Documentation does not impose limits, that would hinder further extensions ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation +- [x] Function code is fully covered by tests +- [x] All possible error states are covered by tests +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index df2cfc8f8b4..60b301d5500 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -1,7 +1,7 @@ # keyDecRef -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-21 21:10 +- end = 2021-02-21 21:25 - moderator = Stefan Hanreich ## Signature @@ -15,67 +15,80 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does + - [ ] change viability to reference counter - [ ] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases + - [ ] add example +- [x] Longer description of function containing common use cases - [ ] Description of functions reads nicely + - [ ] description seems a bit unclear when reading - [ ] `@pre` + - [ ] @pre key is a valid key - [ ] `@post` + - [ ] @post reference counter of the key is decremented by one - [ ] `@invariant` -- [ ] `@param` for every parameter -- [ ] `@return` / `@retval` + - [ ] @invariant key stays a valid key +- [x] `@param` for every parameter +- [x] `@return` / `@retval` - [ ] `@since` -- [ ] `@ingroup` + - [ ] add +- [x] `@ingroup` - [ ] `@see` + - split to multiple lines ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the + - add dec to glossary + - add ref to glossary +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types +- Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- Function is easily extensible, e.g., with flags +- [x] Documentation does not impose limits, that would hinder further extensions ### Tests - [ ] Function code is fully covered by tests + - test decrementing key with reference counter = 0 - [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation + - test decrementing key with reference counter = 0 + - test null pointer +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index ce96901b37e..222cab8671a 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -1,7 +1,7 @@ # keyDup -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-20 18:10 +- end = 2021-02-20 18:35 - moderator = Stefan Hanreich ## Signature @@ -15,67 +15,81 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does + - [ ] could be a bit more specific - [ ] Simple example or snippet how to use the function + - [ ] remove the wrapping function as it only distracts - [ ] Longer description of function containing common use cases + - [ ] be a bit more explicit - [ ] Description of functions reads nicely + - [ ] "Like for a new key" could be formulated better - [ ] `@pre` + - [ ] @pre source must be a valid key - [ ] `@post` + - [ ] @post returns a full copy of the key including all info (metadata, ..) - [ ] `@invariant` -- [ ] `@param` for every parameter -- [ ] `@return` / `@retval` + - [ ] @invariant source stays a valid key +- [x] `@param` for every parameter +- [x] `@return` / `@retval` - [ ] `@since` -- [ ] `@ingroup` + - [ ] add +- [x] `@ingroup` - [ ] `@see` + - [ ] `keyCopy()` ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the + - [ ] add dup to glossary +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types +- Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility - [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] could add flags similar to `keyCopy()` +- [x] Documentation does not impose limits, that would hinder further extensions ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation +- [x] Function code is fully covered by tests + - Error state is hard to check, cause it only appears on null pointers + which gets checked in the function itself already +- [x] All possible error states are covered by tests + - see above +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index 4536f6acd11..42af0064c66 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -1,7 +1,7 @@ # keyGetRef -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-21 21:25 +- end = 2021-02-21 21:35 - moderator = Stefan Hanreich ## Signature @@ -14,68 +14,76 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does +- [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases -- [ ] Description of functions reads nicely + - [ ] add simple example for `keyGetRef()` base case without ks +- [x] Longer description of function containing common use cases +- [x] Description of functions reads nicely - [ ] `@pre` + - [ ] @pre key is a valid key - [ ] `@post` + - [ ] @post key stays unchanged - [ ] `@invariant` -- [ ] `@param` for every parameter -- [ ] `@return` / `@retval` + - [ ] @invariant key stays a valid key +- [x] `@param` for every parameter +- [x] `@return` / `@retval` - [ ] `@since` -- [ ] `@ingroup` + - [ ] add +- [x] `@ingroup` - [ ] `@see` + - maybe add `keyDel()` ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the + - [ ] add Ref to the Glossary +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types +- Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- Function is easily extensible, e.g., with flags +- [x] Documentation does not impose limits, that would hinder further extensions ### Tests -- [ ] Function code is fully covered by tests +- [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation + - [ ] check for null pointer +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index 3c0d0875ecb..71d107418c7 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -1,8 +1,8 @@ # keyIncRef -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 -- moderator = Stefan Hanreich +- start = 2021-01-21 20:50 +- end = 2021-01-21 21:05 +- reviewer = Stefan Hanreich ## Signature @@ -15,67 +15,78 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does + - [ ] change viability to 'reference counter' - [ ] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases -- [ ] Description of functions reads nicely + - [ ] add example +- [x] Longer description of function containing common use cases +- [x] Description of functions reads nicely - [ ] `@pre` + - [ ] @pre key is a valid key - [ ] `@post` + - [ ] @post reference counter of the key is incremented by one - [ ] `@invariant` -- [ ] `@param` for every parameter -- [ ] `@return` / `@retval` + - [ ] @invariant key stays a valid key +- [x] `@param` for every parameter +- [x] `@return` / `@retval` - [ ] `@since` -- [ ] `@ingroup` + - [ ] add +- [x] `@ingroup` - [ ] `@see` + - [ ] add `keyGetRef()` + - [ ] add `keyDecRef()` ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the + - [ ] add inc to glossary + - [ ] add ref to glossary +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types +- Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags +- Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions ### Tests -- [ ] Function code is fully covered by tests +- [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation + - [ ] add test for null pointer +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index ea9c5e83f83..7cdd17793d1 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -1,7 +1,7 @@ # keyIsLocked -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-21 22:15 +- end = 2021-02-21 18:10 - moderator = Stefan Hanreich ## Signature @@ -14,68 +14,81 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does +- [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function + - [ ] add - [ ] Longer description of function containing common use cases -- [ ] Description of functions reads nicely + - [ ] add better description or reference to `keyLocked()` +- [x] Description of functions reads nicely - [ ] `@pre` + - [ ] `key` is a valid key + - [ ] `what` contains valid elektraLockFlags - [ ] `@post` + - [ ] `key` stays unchanged - [ ] `@invariant` + - [ ] `key` stays a valid key - [ ] `@param` for every parameter + - [ ] add - [ ] `@return` / `@retval` + - [ ] change default case to `@return` - [ ] `@since` -- [ ] `@ingroup` + - [ ] add +- [x] `@ingroup` - [ ] `@see` + - [ ] move to bottom ### Naming -- [ ] Abbreviations used in function names must be defined in the +- Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short +- [x] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous + - [ ] rename what to flags? ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types +- [x] Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist + - [ ] move below `keyGetRef()`-family of functions +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [x] Documentation does not impose limits, that would hinder further extensions ### Tests -- [ ] Function code is fully covered by tests +- [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation + - [ ] test for null pointer return value +- [x] All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index a08089255b2..cbcc81c02cb 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -1,7 +1,7 @@ # keyLock -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-21 21:45 +- end = 2021-02-21 22:05 - moderator = Stefan Hanreich ## Signature @@ -14,68 +14,85 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does +- [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases -- [ ] Description of functions reads nicely + - [ ] add +- [x] Longer description of function containing common use cases +- [x] Description of functions reads nicely - [ ] `@pre` + - [ ] key is a valid key + - [ ] what contains valid elektraLockFlags - [ ] `@post` + - [ ] parts of the keys, as stated in the what-parameter, are locked - [ ] `@invariant` + - [ ] key stays a valid key - [ ] `@param` for every parameter + - [ ] key + - [ ] what - [ ] `@return` / `@retval` + - [ ] move above see also + - [ ] move `>0` to default case (`@return`) - [ ] `@since` + - [ ] add - [ ] `@ingroup` + - [ ] add - [ ] `@see` + - [ ] add `keyIsLocked()` ### Naming -- [ ] Abbreviations used in function names must be defined in the +- Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short +- [x] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous + - [ ] rename what to flags? ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) +- [Symbol versioning](/doc/dev/symbol-versioning.md) is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility +- ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types +- [x] Function parameters should use enum types instead of boolean types wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist + - [ ] move below `keyGetRef()`-family of functions +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags +- [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] keys cannot be unlocked ### Tests -- [ ] Function code is fully covered by tests +- [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation + - [ ] test null pointer +- [x] All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary +Also check return values of function in tests \ No newline at end of file From 9c1e53f8cd4213edbf63d158fbe5bc94b560c8e2 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Mon, 22 Feb 2021 00:20:04 +0100 Subject: [PATCH 14/29] docs: add newlines to api-review markdowns --- doc/api_review/core/keyClear.md | 38 +++++++++++------------ doc/api_review/core/keyDecRef.md | 48 +++++++++++++++--------------- doc/api_review/core/keyDup.md | 46 ++++++++++++++-------------- doc/api_review/core/keyGetRef.md | 30 +++++++++---------- doc/api_review/core/keyIncRef.md | 38 +++++++++++------------ doc/api_review/core/keyIsLocked.md | 38 +++++++++++------------ doc/api_review/core/keyLock.md | 48 +++++++++++++++--------------- 7 files changed, 143 insertions(+), 143 deletions(-) diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index 77a5724afb4..fb8a1f7792a 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -20,21 +20,21 @@ - [x] Simple example or snippet how to use the function - [ ] Longer description of function containing common use cases - be more explicit which data is actually included -- [ ] Description of functions reads nicely - - [ ] very short sentences -- [ ] `@pre` - - [ ] @pre key is a valid key -- [ ] `@post` - - [ ] @post key contains not internal data -- [ ] `@invariant` - - [ ] @invariant key stays a valid key +- [ ] Description of functions reads nicely + - [ ] very short sentences +- [ ] `@pre` + - [ ] @pre key is a valid key +- [ ] `@post` + - [ ] @post key contains not internal data +- [ ] `@invariant` + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter -- [ ] `@return` / `@retval` - - [ ] mark default case with `@return` -- [ ] `@since` - - [ ] add +- [ ] `@return` / `@retval` + - [ ] mark default case with `@return` +- [ ] `@since` + - [ ] add - [x] `@ingroup` -- [ ] `@see` +- [ ] `@see` - [ ] maybe `keyDel()` ### Naming @@ -69,10 +69,10 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen - - [ ] swap with `keyDel()` -- [ ] No functions with similar purpose exist - - [ ] new keyCopy can also clear a key, maybe make `keyClear` an alias? +- [ ] Order of signatures in kdb.h.in is the same as Doxygen + - [ ] swap with `keyDel()` +- [ ] No functions with similar purpose exist + - [ ] new keyCopy can also clear a key, maybe make `keyClear` an alias? ### Memory Management @@ -80,8 +80,8 @@ ### Extensibility -- [ ] Function is easily extensible, e.g., with flags - - [ ] could add flags for clearing parts of the key like `keyCopy()` +- [ ] Function is easily extensible, e.g., with flags + - [ ] could add flags for clearing parts of the key like `keyCopy()` - [x] Documentation does not impose limits, that would hinder further extensions ### Tests diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index 60b301d5500..fa360f8654e 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -14,33 +14,33 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does - - [ ] change viability to reference counter -- [ ] Simple example or snippet how to use the function - - [ ] add example +- [ ] First line explains briefly what the function does + - [ ] change viability to reference counter +- [ ] Simple example or snippet how to use the function + - [ ] add example - [x] Longer description of function containing common use cases -- [ ] Description of functions reads nicely - - [ ] description seems a bit unclear when reading -- [ ] `@pre` - - [ ] @pre key is a valid key -- [ ] `@post` - - [ ] @post reference counter of the key is decremented by one -- [ ] `@invariant` - - [ ] @invariant key stays a valid key +- [ ] Description of functions reads nicely + - [ ] description seems a bit unclear when reading +- [ ] `@pre` + - [ ] @pre key is a valid key +- [ ] `@post` + - [ ] @post reference counter of the key is decremented by one +- [ ] `@invariant` + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` -- [ ] `@since` - - [ ] add +- [ ] `@since` + - [ ] add - [x] `@ingroup` -- [ ] `@see` - - split to multiple lines +- [ ] `@see` + - split to multiple lines ### Naming - [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - - add dec to glossary - - add ref to glossary + [Glossary](/doc/help/elektra-glossary.md) + - add dec to glossary + - add ref to glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the @@ -83,11 +83,11 @@ ### Tests -- [ ] Function code is fully covered by tests - - test decrementing key with reference counter = 0 -- [ ] All possible error states are covered by tests - - test decrementing key with reference counter = 0 - - test null pointer +- [ ] Function code is fully covered by tests + - test decrementing key with reference counter = 0 +- [ ] All possible error states are covered by tests + - test decrementing key with reference counter = 0 + - test null pointer - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index 222cab8671a..42c56ca5249 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -14,33 +14,33 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does - - [ ] could be a bit more specific -- [ ] Simple example or snippet how to use the function - - [ ] remove the wrapping function as it only distracts -- [ ] Longer description of function containing common use cases - - [ ] be a bit more explicit -- [ ] Description of functions reads nicely - - [ ] "Like for a new key" could be formulated better -- [ ] `@pre` - - [ ] @pre source must be a valid key -- [ ] `@post` - - [ ] @post returns a full copy of the key including all info (metadata, ..) -- [ ] `@invariant` - - [ ] @invariant source stays a valid key +- [ ] First line explains briefly what the function does + - [ ] could be a bit more specific +- [ ] Simple example or snippet how to use the function + - [ ] remove the wrapping function as it only distracts +- [ ] Longer description of function containing common use cases + - [ ] be a bit more explicit +- [ ] Description of functions reads nicely + - [ ] "Like for a new key" could be formulated better +- [ ] `@pre` + - [ ] @pre source must be a valid key +- [ ] `@post` + - [ ] @post returns a full copy of the key including all info (metadata, ..) +- [ ] `@invariant` + - [ ] @invariant source stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` -- [ ] `@since` - - [ ] add +- [ ] `@since` + - [ ] add - [x] `@ingroup` -- [ ] `@see` +- [ ] `@see` - [ ] `keyCopy()` ### Naming - [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - - [ ] add dup to glossary + [Glossary](/doc/help/elektra-glossary.md) + - [ ] add dup to glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the @@ -78,16 +78,16 @@ ### Extensibility -- [ ] Function is easily extensible, e.g., with flags - - [ ] could add flags similar to `keyCopy()` +- [ ] Function is easily extensible, e.g., with flags + - [ ] could add flags similar to `keyCopy()` - [x] Documentation does not impose limits, that would hinder further extensions ### Tests -- [x] Function code is fully covered by tests +- [x] Function code is fully covered by tests - Error state is hard to check, cause it only appears on null pointers which gets checked in the function itself already -- [x] All possible error states are covered by tests +- [x] All possible error states are covered by tests - see above - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index 42af0064c66..c698aa17ff0 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -15,29 +15,29 @@ (bullet points are in order of appearance) - [x] First line explains briefly what the function does -- [ ] Simple example or snippet how to use the function - - [ ] add simple example for `keyGetRef()` base case without ks +- [ ] Simple example or snippet how to use the function + - [ ] add simple example for `keyGetRef()` base case without ks - [x] Longer description of function containing common use cases - [x] Description of functions reads nicely -- [ ] `@pre` - - [ ] @pre key is a valid key -- [ ] `@post` - - [ ] @post key stays unchanged -- [ ] `@invariant` - - [ ] @invariant key stays a valid key +- [ ] `@pre` + - [ ] @pre key is a valid key +- [ ] `@post` + - [ ] @post key stays unchanged +- [ ] `@invariant` + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` -- [ ] `@since` - - [ ] add +- [ ] `@since` + - [ ] add - [x] `@ingroup` -- [ ] `@see` - - maybe add `keyDel()` +- [ ] `@see` + - maybe add `keyDel()` ### Naming - [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - - [ ] add Ref to the Glossary + [Glossary](/doc/help/elektra-glossary.md) + - [ ] add Ref to the Glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the @@ -81,7 +81,7 @@ ### Tests - [x] Function code is fully covered by tests -- [ ] All possible error states are covered by tests +- [ ] All possible error states are covered by tests - [ ] check for null pointer - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index 71d107418c7..74cbd40cb92 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -14,33 +14,33 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does - - [ ] change viability to 'reference counter' -- [ ] Simple example or snippet how to use the function - - [ ] add example +- [ ] First line explains briefly what the function does + - [ ] change viability to 'reference counter' +- [ ] Simple example or snippet how to use the function + - [ ] add example - [x] Longer description of function containing common use cases - [x] Description of functions reads nicely -- [ ] `@pre` - - [ ] @pre key is a valid key -- [ ] `@post` - - [ ] @post reference counter of the key is incremented by one -- [ ] `@invariant` - - [ ] @invariant key stays a valid key +- [ ] `@pre` + - [ ] @pre key is a valid key +- [ ] `@post` + - [ ] @post reference counter of the key is incremented by one +- [ ] `@invariant` + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` -- [ ] `@since` - - [ ] add +- [ ] `@since` + - [ ] add - [x] `@ingroup` -- [ ] `@see` - - [ ] add `keyGetRef()` +- [ ] `@see` + - [ ] add `keyGetRef()` - [ ] add `keyDecRef()` ### Naming - [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) - - [ ] add inc to glossary - - [ ] add ref to glossary + [Glossary](/doc/help/elektra-glossary.md) + - [ ] add inc to glossary + - [ ] add ref to glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the @@ -84,8 +84,8 @@ ### Tests - [x] Function code is fully covered by tests -- [ ] All possible error states are covered by tests - - [ ] add test for null pointer +- [ ] All possible error states are covered by tests + - [ ] add test for null pointer - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index 7cdd17793d1..021cc44f553 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -20,21 +20,21 @@ - [ ] Longer description of function containing common use cases - [ ] add better description or reference to `keyLocked()` - [x] Description of functions reads nicely -- [ ] `@pre` - - [ ] `key` is a valid key - - [ ] `what` contains valid elektraLockFlags -- [ ] `@post` - - [ ] `key` stays unchanged -- [ ] `@invariant` - - [ ] `key` stays a valid key -- [ ] `@param` for every parameter - - [ ] add -- [ ] `@return` / `@retval` - - [ ] change default case to `@return` -- [ ] `@since` - - [ ] add +- [ ] `@pre` + - [ ] `key` is a valid key + - [ ] `what` contains valid elektraLockFlags +- [ ] `@post` + - [ ] `key` stays unchanged +- [ ] `@invariant` + - [ ] `key` stays a valid key +- [ ] `@param` for every parameter + - [ ] add +- [ ] `@return` / `@retval` + - [ ] change default case to `@return` +- [ ] `@since` + - [ ] add - [x] `@ingroup` -- [ ] `@see` +- [ ] `@see` - [ ] move to bottom ### Naming @@ -46,7 +46,7 @@ - Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous - [ ] rename what to flags? ### Compatibility @@ -70,8 +70,8 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen - - [ ] move below `keyGetRef()`-family of functions +- [ ] Order of signatures in kdb.h.in is the same as Doxygen + - [ ] move below `keyGetRef()`-family of functions - [x] No functions with similar purpose exist ### Memory Management @@ -86,8 +86,8 @@ ### Tests - [x] Function code is fully covered by tests -- [ ] All possible error states are covered by tests - - [ ] test for null pointer return value +- [ ] All possible error states are covered by tests + - [ ] test for null pointer return value - [x] All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index cbcc81c02cb..6e51b3db237 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -19,25 +19,25 @@ - [ ] add - [x] Longer description of function containing common use cases - [x] Description of functions reads nicely -- [ ] `@pre` - - [ ] key is a valid key - - [ ] what contains valid elektraLockFlags -- [ ] `@post` - - [ ] parts of the keys, as stated in the what-parameter, are locked -- [ ] `@invariant` - - [ ] key stays a valid key -- [ ] `@param` for every parameter - - [ ] key - - [ ] what -- [ ] `@return` / `@retval` - - [ ] move above see also - - [ ] move `>0` to default case (`@return`) -- [ ] `@since` - - [ ] add -- [ ] `@ingroup` - - [ ] add -- [ ] `@see` - - [ ] add `keyIsLocked()` +- [ ] `@pre` + - [ ] key is a valid key + - [ ] what contains valid elektraLockFlags +- [ ] `@post` + - [ ] parts of the keys, as stated in the what-parameter, are locked +- [ ] `@invariant` + - [ ] key stays a valid key +- [ ] `@param` for every parameter + - [ ] key + - [ ] what +- [ ] `@return` / `@retval` + - [ ] move above see also + - [ ] move `>0` to default case (`@return`) +- [ ] `@since` + - [ ] add +- [ ] `@ingroup` + - [ ] add +- [ ] `@see` + - [ ] add `keyIsLocked()` ### Naming @@ -48,7 +48,7 @@ - [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- [ ] Parameter names should be clear and unambiguous - [ ] rename what to flags? ### Compatibility @@ -72,7 +72,7 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - [ ] move below `keyGetRef()`-family of functions - [x] No functions with similar purpose exist @@ -83,14 +83,14 @@ ### Extensibility - [x] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [ ] Documentation does not impose limits, that would hinder further extensions - [ ] keys cannot be unlocked ### Tests - [x] Function code is fully covered by tests -- [ ] All possible error states are covered by tests - - [ ] test null pointer +- [ ] All possible error states are covered by tests + - [ ] test null pointer - [x] All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation From 50b3f8b7eb1a0d6dc5748e98ec99dca4aa24d093 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Mon, 22 Feb 2021 00:20:41 +0100 Subject: [PATCH 15/29] docs: prettier formatting --- doc/api_review/core/keyClear.md | 38 +++++++++++++-------------- doc/api_review/core/keyDecRef.md | 34 ++++++++++++------------ doc/api_review/core/keyDup.md | 36 ++++++++++++------------- doc/api_review/core/keyGetRef.md | 24 ++++++++--------- doc/api_review/core/keyIncRef.md | 30 ++++++++++----------- doc/api_review/core/keyIsLocked.md | 36 ++++++++++++------------- doc/api_review/core/keyLock.md | 42 +++++++++++++++--------------- 7 files changed, 118 insertions(+), 122 deletions(-) diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index fb8a1f7792a..cec5b5335d8 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -14,37 +14,35 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does - - remove first line, second line could be improved a bit - (what is meant with internal data, exactly? is the name included?) +- [ ] First line explains briefly what the function does - remove first line, second line could be improved a bit + (what is meant with internal data, exactly? is the name included?) - [x] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases - - be more explicit which data is actually included +- [ ] Longer description of function containing common use cases - be more explicit which data is actually included - [ ] Description of functions reads nicely - - [ ] very short sentences + - [ ] very short sentences - [ ] `@pre` - - [ ] @pre key is a valid key + - [ ] @pre key is a valid key - [ ] `@post` - - [ ] @post key contains not internal data + - [ ] @post key contains not internal data - [ ] `@invariant` - - [ ] @invariant key stays a valid key + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter - [ ] `@return` / `@retval` - - [ ] mark default case with `@return` + - [ ] mark default case with `@return` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - [ ] maybe `keyDel()` + - [ ] maybe `keyDel()` ### Naming - Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [x] Parameter names should be clear and unambiguous @@ -53,14 +51,14 @@ (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types - Function parameters should use enum types instead of boolean types - wherever sensible + wherever sensible - [x] Wherever possible, function parameters should be `const` - [x] Wherever possible, return types should be `const` - [x] Functions should have the least amount of parameters feasible @@ -70,9 +68,9 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen - - [ ] swap with `keyDel()` + - [ ] swap with `keyDel()` - [ ] No functions with similar purpose exist - - [ ] new keyCopy can also clear a key, maybe make `keyClear` an alias? + - [ ] new keyCopy can also clear a key, maybe make `keyClear` an alias? ### Memory Management @@ -81,7 +79,7 @@ ### Extensibility - [ ] Function is easily extensible, e.g., with flags - - [ ] could add flags for clearing parts of the key like `keyCopy()` + - [ ] could add flags for clearing parts of the key like `keyCopy()` - [x] Documentation does not impose limits, that would hinder further extensions ### Tests diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index fa360f8654e..415b6f7fe9a 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -15,36 +15,36 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does - - [ ] change viability to reference counter + - [ ] change viability to reference counter - [ ] Simple example or snippet how to use the function - - [ ] add example + - [ ] add example - [x] Longer description of function containing common use cases - [ ] Description of functions reads nicely - - [ ] description seems a bit unclear when reading + - [ ] description seems a bit unclear when reading - [ ] `@pre` - - [ ] @pre key is a valid key + - [ ] @pre key is a valid key - [ ] `@post` - - [ ] @post reference counter of the key is decremented by one + - [ ] @post reference counter of the key is decremented by one - [ ] `@invariant` - - [ ] @invariant key stays a valid key + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - split to multiple lines + - split to multiple lines ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - - add dec to glossary - - add ref to glossary + - add dec to glossary + - add ref to glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [x] Parameter names should be clear and unambiguous @@ -53,14 +53,14 @@ (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types - Function parameters should use enum types instead of boolean types - wherever sensible + wherever sensible - [x] Wherever possible, function parameters should be `const` - [x] Wherever possible, return types should be `const` - [x] Functions should have the least amount of parameters feasible @@ -84,10 +84,10 @@ ### Tests - [ ] Function code is fully covered by tests - - test decrementing key with reference counter = 0 + - test decrementing key with reference counter = 0 - [ ] All possible error states are covered by tests - - test decrementing key with reference counter = 0 - - test null pointer + - test decrementing key with reference counter = 0 + - test null pointer - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index 42c56ca5249..052ad3f6620 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -15,36 +15,36 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does - - [ ] could be a bit more specific + - [ ] could be a bit more specific - [ ] Simple example or snippet how to use the function - - [ ] remove the wrapping function as it only distracts + - [ ] remove the wrapping function as it only distracts - [ ] Longer description of function containing common use cases - - [ ] be a bit more explicit + - [ ] be a bit more explicit - [ ] Description of functions reads nicely - - [ ] "Like for a new key" could be formulated better + - [ ] "Like for a new key" could be formulated better - [ ] `@pre` - - [ ] @pre source must be a valid key + - [ ] @pre source must be a valid key - [ ] `@post` - - [ ] @post returns a full copy of the key including all info (metadata, ..) + - [ ] @post returns a full copy of the key including all info (metadata, ..) - [ ] `@invariant` - - [ ] @invariant source stays a valid key + - [ ] @invariant source stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - [ ] `keyCopy()` + - [ ] `keyCopy()` ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - - [ ] add dup to glossary + - [ ] add dup to glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [x] Parameter names should be clear and unambiguous @@ -53,14 +53,14 @@ (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types - Function parameters should use enum types instead of boolean types - wherever sensible + wherever sensible - [x] Wherever possible, function parameters should be `const` - [x] Wherever possible, return types should be `const` - [x] Functions should have the least amount of parameters feasible @@ -79,16 +79,16 @@ ### Extensibility - [ ] Function is easily extensible, e.g., with flags - - [ ] could add flags similar to `keyCopy()` + - [ ] could add flags similar to `keyCopy()` - [x] Documentation does not impose limits, that would hinder further extensions ### Tests - [x] Function code is fully covered by tests - - Error state is hard to check, cause it only appears on null pointers - which gets checked in the function itself already + - Error state is hard to check, cause it only appears on null pointers + which gets checked in the function itself already - [x] All possible error states are covered by tests - - see above + - see above - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index c698aa17ff0..f21bf1a4e72 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -16,32 +16,32 @@ - [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function - - [ ] add simple example for `keyGetRef()` base case without ks + - [ ] add simple example for `keyGetRef()` base case without ks - [x] Longer description of function containing common use cases - [x] Description of functions reads nicely - [ ] `@pre` - - [ ] @pre key is a valid key + - [ ] @pre key is a valid key - [ ] `@post` - - [ ] @post key stays unchanged + - [ ] @post key stays unchanged - [ ] `@invariant` - - [ ] @invariant key stays a valid key + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - maybe add `keyDel()` + - maybe add `keyDel()` ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - - [ ] add Ref to the Glossary + - [ ] add Ref to the Glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [x] Parameter names should be clear and unambiguous @@ -50,14 +50,14 @@ (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types - Function parameters should use enum types instead of boolean types - wherever sensible + wherever sensible - [x] Wherever possible, function parameters should be `const` - [x] Wherever possible, return types should be `const` - [x] Functions should have the least amount of parameters feasible @@ -82,7 +82,7 @@ - [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests - - [ ] check for null pointer + - [ ] check for null pointer - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index 74cbd40cb92..80eafb9a6eb 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -15,36 +15,36 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does - - [ ] change viability to 'reference counter' + - [ ] change viability to 'reference counter' - [ ] Simple example or snippet how to use the function - - [ ] add example + - [ ] add example - [x] Longer description of function containing common use cases - [x] Description of functions reads nicely - [ ] `@pre` - - [ ] @pre key is a valid key + - [ ] @pre key is a valid key - [ ] `@post` - - [ ] @post reference counter of the key is incremented by one + - [ ] @post reference counter of the key is incremented by one - [ ] `@invariant` - - [ ] @invariant key stays a valid key + - [ ] @invariant key stays a valid key - [x] `@param` for every parameter - [x] `@return` / `@retval` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - [ ] add `keyGetRef()` - - [ ] add `keyDecRef()` + - [ ] add `keyGetRef()` + - [ ] add `keyDecRef()` ### Naming - [ ] Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - - [ ] add inc to glossary - - [ ] add ref to glossary + - [ ] add inc to glossary + - [ ] add ref to glossary - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [x] Parameter names should be clear and unambiguous @@ -53,14 +53,14 @@ (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types - Function parameters should use enum types instead of boolean types - wherever sensible + wherever sensible - [x] Wherever possible, function parameters should be `const` - [x] Wherever possible, return types should be `const` - [x] Functions should have the least amount of parameters feasible @@ -85,7 +85,7 @@ - [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests - - [ ] add test for null pointer + - [ ] add test for null pointer - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index 021cc44f553..86ccea564e3 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -15,48 +15,46 @@ (bullet points are in order of appearance) - [x] First line explains briefly what the function does -- [ ] Simple example or snippet how to use the function - - [ ] add -- [ ] Longer description of function containing common use cases - - [ ] add better description or reference to `keyLocked()` +- [ ] Simple example or snippet how to use the function - [ ] add +- [ ] Longer description of function containing common use cases - [ ] add better description or reference to `keyLocked()` - [x] Description of functions reads nicely - [ ] `@pre` - - [ ] `key` is a valid key - - [ ] `what` contains valid elektraLockFlags + - [ ] `key` is a valid key + - [ ] `what` contains valid elektraLockFlags - [ ] `@post` - - [ ] `key` stays unchanged + - [ ] `key` stays unchanged - [ ] `@invariant` - - [ ] `key` stays a valid key + - [ ] `key` stays a valid key - [ ] `@param` for every parameter - - [ ] add + - [ ] add - [ ] `@return` / `@retval` - - [ ] change default case to `@return` + - [ ] change default case to `@return` - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - [ ] move to bottom + - [ ] move to bottom ### Naming - Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous - - [ ] rename what to flags? + - [ ] rename what to flags? ### Compatibility (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types @@ -71,7 +69,7 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen - - [ ] move below `keyGetRef()`-family of functions + - [ ] move below `keyGetRef()`-family of functions - [x] No functions with similar purpose exist ### Memory Management @@ -87,7 +85,7 @@ - [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests - - [ ] test for null pointer return value + - [ ] test for null pointer return value - [x] All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index 6e51b3db237..e3cbb045b54 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -15,50 +15,49 @@ (bullet points are in order of appearance) - [x] First line explains briefly what the function does -- [ ] Simple example or snippet how to use the function - - [ ] add +- [ ] Simple example or snippet how to use the function - [ ] add - [x] Longer description of function containing common use cases - [x] Description of functions reads nicely - [ ] `@pre` - - [ ] key is a valid key - - [ ] what contains valid elektraLockFlags + - [ ] key is a valid key + - [ ] what contains valid elektraLockFlags - [ ] `@post` - - [ ] parts of the keys, as stated in the what-parameter, are locked + - [ ] parts of the keys, as stated in the what-parameter, are locked - [ ] `@invariant` - - [ ] key stays a valid key + - [ ] key stays a valid key - [ ] `@param` for every parameter - - [ ] key - - [ ] what + - [ ] key + - [ ] what - [ ] `@return` / `@retval` - - [ ] move above see also - - [ ] move `>0` to default case (`@return`) + - [ ] move above see also + - [ ] move `>0` to default case (`@return`) - [ ] `@since` - - [ ] add + - [ ] add - [ ] `@ingroup` - - [ ] add + - [ ] add - [ ] `@see` - - [ ] add `keyIsLocked()` + - [ ] add `keyIsLocked()` ### Naming - Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) + [Glossary](/doc/help/elektra-glossary.md) - [x] Function names should neither be too long, nor too short - [x] Function name should be clear and unambiguous - [x] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - [x] Parameter names should neither be too long, nor too short - [ ] Parameter names should be clear and unambiguous - - [ ] rename what to flags? + - [ ] rename what to flags? ### Compatibility (only in PRs) - [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes + is correct for breaking changes - ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) + to add additional symbols is fine) ### Parameter & Return Types @@ -73,7 +72,7 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix - [ ] Order of signatures in kdb.h.in is the same as Doxygen - - [ ] move below `keyGetRef()`-family of functions + - [ ] move below `keyGetRef()`-family of functions - [x] No functions with similar purpose exist ### Memory Management @@ -84,15 +83,16 @@ - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] keys cannot be unlocked + - [ ] keys cannot be unlocked ### Tests - [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests - - [ ] test null pointer + - [ ] test null pointer - [x] All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation ## Summary -Also check return values of function in tests \ No newline at end of file + +Also check return values of function in tests From 44db8c9e977f0ee22c87e441246e732ea350cac6 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Mon, 22 Feb 2021 00:52:25 +0100 Subject: [PATCH 16/29] fix metadata in reviews --- doc/api_review/core/keyClear.md | 4 ++-- doc/api_review/core/keyDecRef.md | 2 +- doc/api_review/core/keyIncRef.md | 4 ++-- doc/api_review/core/keyIsLocked.md | 4 ++-- doc/api_review/core/keyLock.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index cec5b5335d8..c9e93789b2a 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -1,7 +1,7 @@ # keyClear -- start = 2021-01-23 18:40 -- end = 2021-01-23 19:00 +- start = 2021-02-21 22:40 +- end = 2021-02-21 23:05 - reviewer = Stefan Hanreich ## Signature diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index 415b6f7fe9a..f73f987782a 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -2,7 +2,7 @@ - start = 2021-02-21 21:10 - end = 2021-02-21 21:25 -- moderator = Stefan Hanreich +- reviewer = Stefan Hanreich ## Signature diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index 80eafb9a6eb..4d1b726f03d 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -1,7 +1,7 @@ # keyIncRef -- start = 2021-01-21 20:50 -- end = 2021-01-21 21:05 +- start = 2021-02-21 20:50 +- end = 2021-02-21 21:05 - reviewer = Stefan Hanreich ## Signature diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index 86ccea564e3..d5f1bd271e5 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -1,8 +1,8 @@ # keyIsLocked - start = 2021-02-21 22:15 -- end = 2021-02-21 18:10 -- moderator = Stefan Hanreich +- end = 2021-02-21 22:40 +- reviewer = Stefan Hanreich ## Signature diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index e3cbb045b54..d5950eb1638 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -2,7 +2,7 @@ - start = 2021-02-21 21:45 - end = 2021-02-21 22:05 -- moderator = Stefan Hanreich +- reviewer = Stefan Hanreich ## Signature From acadb2378dc433692d14426e602764ca6b7fed9e Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 23 Feb 2021 00:12:46 +0100 Subject: [PATCH 17/29] add peer reviews --- doc/api_review/core/keyGetName.md | 114 +++++++++++++++++--------- doc/api_review/core/keyGetNameSize.md | 101 +++++++++++++---------- doc/api_review/core/keySetString.md | 105 ++++++++++++++---------- 3 files changed, 197 insertions(+), 123 deletions(-) diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index 00b2052c155..5686e5c8165 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -1,8 +1,9 @@ # keyGetName -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-22 13:40 +- end = 2021-02-22 14:20 - moderator = Stefan Hanreich +- reviewer = Philipp Gackstatter ## Signature @@ -14,68 +15,105 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does -- [ ] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases +- [ ] First line explains briefly what the function does + - [ ] owner still recent? +- [ ] Simple example or snippet how to use the function + - [ ] move up +- [ ] Longer description of function containing common use cases + - [ ] maxSize special case has very long description (>50% of body) + - [ ] maxSize special case move description to pre / post / return values + - [ ] mention explicitly, that user has to manage their buffer + - [ ] move special case 'not enough space' to return values / pre / post - [ ] Description of functions reads nicely -- [ ] `@pre` -- [ ] `@post` -- [ ] `@invariant` -- [ ] `@param` for every parameter -- [ ] `@return` / `@retval` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] `@see` + - [ ] remove / define abbreviated (make it more explicit) + - [ ] "Writes keyName of `key` into the provided buffer `returnedName` if it is shorter than `maxSize`" +- [ ] `@pre` + - [ ] `key` is a valid Key + - [ ] `returnedName` is a pre-allocated buffer + - [ ] maxSize is the size of `returnedName` +- [ ] `@post` + - [ ] `returnedName` contains the name of the Key + - [ ] `key` is not modified +- [ ] `@invariant` + - [ ] `key` is not modified +- [ ] `@param` for every parameter + - [ ] `returnedName`: pre-allocated buffer to write the key name into +- [ ] `@return` / `@retval` + - [ ] `1`: when only a null-terminator was written + - [ ] `-1`: then -> than + - [ ] `-1`: standardize / change 'keyname' / 'key name' or 'Key name' + - [ ] `-1` check if null pointer case is even still applicable + - [ ] `-1` split into two lines: maxSize / NULL pointer +- [ ] `@since` + - [ ] add +- [x] `@ingroup` +- [ ] `@see` + - [ ] keyName + - [ ] keyGetUnescapedName + - [ ] keyGetBaseName + - [ ] keyGetNamespace ### Naming -- [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous +- Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [x] Function names should neither be too long, nor too short +- [ ] Function name should be clear and unambiguous + - [ ] `keyName` vs `keyGetName()` - [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous + [Glossary](/doc/help/elektra-glossary.md) + - [ ] max - maybe just rename to `bufferSize` +- [ ] Parameter names should neither be too long, nor too short + - [ ] `returnedName` -> `name` / `nameBuffer` +- [ ] Parameter names should be clear and unambiguous + - [ ] `maxSize` -> `bufferSize` ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) +- [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types - wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- Function parameters should use enum types instead of boolean types + wherever sensible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [ ] Order of signatures in kdb.h.in is the same as Doxygen - wrong order +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [ ] Memory Management should be handled by the function wherever possible + - [ ] pass variable and return size instead + - [ ] remove `maxSize` param ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] nothing is written on maxSize < nameSize (would be fixed with + memory management suggestion from above) ### Tests - [ ] Function code is fully covered by tests + - Lines 365 / 366 - [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation + - test empty string +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary + +Different error codes for different errors diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md index a7e1b7c6af1..d4a171d337b 100644 --- a/doc/api_review/core/keyGetNameSize.md +++ b/doc/api_review/core/keyGetNameSize.md @@ -1,8 +1,9 @@ # keyGetNameSize -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-22 13:10 +- end = 2021-02-22 13:40 - moderator = Stefan Hanreich +- reviewer = Philipp Gackstatter ## Signature @@ -14,68 +15,82 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does -- [ ] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases -- [ ] Description of functions reads nicely -- [ ] `@pre` -- [ ] `@post` -- [ ] `@invariant` -- [ ] `@param` for every parameter -- [ ] `@return` / `@retval` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] `@see` +- [ ] First line explains briefly what the function does + - [ ] only describes return value + - [ ] null-termination + - [ ] mit return mergen +- [ ] Simple example or snippet how to use the function + - [ ] add +- [ ] Longer description of function containing common use cases + - [ ] better describe common use case + - [ ] example for error case + - [ ] example for empty string +- [x] Description of functions reads nicely +- [ ] `@pre` + - [ ] add 'Key should be valid' +- [ ] `@post` + - [ ] add 'key doesn't get modified' +- [ ] `@invariant` + - [ ] add 'key doesn't get modified' +- [ ] `@param` for every parameter + - [ ] 'key object to get the size of the name from' + - [ ] make consistent +- [ ] `@return` / `@retval` + - [ ] without owner? +- [ ] `@see` + - [ ] add parentheses to keyGetUnescapedNameSize ### Naming - -- [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [x] Parameter names should neither be too long, nor too short +- [x] Parameter names should be clear and unambiguous ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) +- [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types - wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- Function parameters should use enum types instead of boolean types + wherever sensible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [x] Documentation does not impose limits, that would hinder further extensions ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation +- [x] Function code is fully covered by tests +- [ ] All possible error states are covered by tests + - [ ] add test case for NULL pointer +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary + +try splitting ifs to two lines, for better coverage reports diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index 784fa5aaeb1..7a7fa629c03 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -1,8 +1,9 @@ # keySetString -- start = 2021-01-23 18:10 -- end = 2021-01-23 18:10 +- start = 2021-02-21 12:20 +- end = 2021-02-21 18:10 - moderator = Stefan Hanreich +- reviewer = Dominic Jäger ## Signature @@ -14,68 +15,88 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does -- [ ] Simple example or snippet how to use the function -- [ ] Longer description of function containing common use cases -- [ ] Description of functions reads nicely -- [ ] `@pre` -- [ ] `@post` -- [ ] `@invariant` -- [ ] `@param` for every parameter -- [ ] `@return` / `@retval` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] `@see` +- [x] First line explains briefly what the function does +- [ ] Simple example or snippet how to use the function + - [ ] add +- Longer description of function containing common use cases - All uses cases covered by brief description +- [ ] Description of functions reads nicely + - [ ] 'as new string value' seems strange + - [ ] 'private copy' is unclear +- [ ] `@pre` + - [ ] add +- [ ] `@post` + - [ ] add + - [ ] string saved as UTF-8 in backend +- [ ] `@invariant` + - [ ] add +- [ ] `@param` for every parameter + - [ ] 'text string' maybe redundant? +- [x] `@return` / `@retval` +- [ ] `@since` + - [ ] add +- [x] `@ingroup` +- [ ] `@see` + - [ ] split to multiple lines + - [ ] shortly explain differences between `keyString` `keyGetString` + - [ ] add `keySetBinary` ? + - [ ] remove `keyValue`, as it is not related to string ### Naming -- [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Parameter names should be clear and unambiguous +- Abbreviations used in function names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [x] Function names should neither be too long, nor too short +- [x] Function name should be clear and unambiguous +- Abbreviations used in parameter names must be defined in the + [Glossary](/doc/help/elektra-glossary.md) +- [ ] Parameter names should neither be too long, nor too short + - [ ] `newStringValue` - remove Value? +- [x] Parameter names should be clear and unambiguous ### Compatibility (only in PRs) -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) +- [Symbol versioning](/doc/dev/symbol-versioning.md) + is correct for breaking changes +- ABI/API changes are forward-compatible (breaking backwards-compatibility + to add additional symbols is fine) ### Parameter & Return Types -- [ ] Function parameters should use enum types instead of boolean types - wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible +- Function parameters should use enum types instead of boolean types + wherever sensible +- [x] Wherever possible, function parameters should be `const` +- [x] Wherever possible, return types should be `const` +- [x] Functions should have the least amount of parameters feasible ### Structural Clarity -- [ ] Functions should do exactly one thing -- [ ] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen -- [ ] No functions with similar purpose exist +- [x] Functions should do exactly one thing +- [x] Function name has the appropriate prefix +- [x] Order of signatures in kdb.h.in is the same as Doxygen +- [x] No functions with similar purpose exist ### Memory Management -- [ ] Memory Management should be handled by the function wherever possible +- [x] Memory Management should be handled by the function wherever possible ### Extensibility -- [ ] Function is easily extensible, e.g., with flags -- [ ] Documentation does not impose limits, that would hinder further extensions +- [x] Function is easily extensible, e.g., with flags +- [ ] Documentation does not impose limits, that would hinder further extensions + - [ ] iconv-Plugin + - [ ] UTF-8 + - [ ] Return Value on NULL ### Tests -- [ ] Function code is fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible enum values are covered by tests -- [ ] No inconsistencies between tests and documentation +- [x] Function code is fully covered by tests +- [x] All possible error states are covered by tests +- All possible enum values are covered by tests +- [x] No inconsistencies between tests and documentation ## Summary + +Behaviour when `newStringValue` is a NULL pointer seems strange +Exact difference keyString keyGetString ? From be1018d5ce6da38b5ecd6d72aeee9cde9e50750d Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 23 Feb 2021 00:14:19 +0100 Subject: [PATCH 18/29] docs: reformat --- doc/api_review/core/keyGetName.md | 87 +++++++++++++-------------- doc/api_review/core/keyGetNameSize.md | 31 +++++----- doc/api_review/core/keySetString.md | 38 ++++++------ 3 files changed, 77 insertions(+), 79 deletions(-) diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index 5686e5c8165..0e4d2c62723 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -15,43 +15,42 @@ (bullet points are in order of appearance) -- [ ] First line explains briefly what the function does - - [ ] owner still recent? +- [ ] First line explains briefly what the function does + - [ ] owner still recent? - [ ] Simple example or snippet how to use the function - - [ ] move up -- [ ] Longer description of function containing common use cases - - [ ] maxSize special case has very long description (>50% of body) - - [ ] maxSize special case move description to pre / post / return values - - [ ] mention explicitly, that user has to manage their buffer - - [ ] move special case 'not enough space' to return values / pre / post -- [ ] Description of functions reads nicely - - [ ] remove / define abbreviated (make it more explicit) - - [ ] "Writes keyName of `key` into the provided buffer `returnedName` if it is shorter than `maxSize`" -- [ ] `@pre` - - [ ] `key` is a valid Key - - [ ] `returnedName` is a pre-allocated buffer - - [ ] maxSize is the size of `returnedName` -- [ ] `@post` - - [ ] `returnedName` contains the name of the Key - - [ ] `key` is not modified -- [ ] `@invariant` - - [ ] `key` is not modified -- [ ] `@param` for every parameter - - [ ] `returnedName`: pre-allocated buffer to write the key name into -- [ ] `@return` / `@retval` - - [ ] `1`: when only a null-terminator was written - - [ ] `-1`: then -> than - - [ ] `-1`: standardize / change 'keyname' / 'key name' or 'Key name' - - [ ] `-1` check if null pointer case is even still applicable - - [ ] `-1` split into two lines: maxSize / NULL pointer + - [ ] move up +- [ ] Longer description of function containing common use cases + - [ ] maxSize special case has very long description (>50% of body) + - [ ] maxSize special case move description to pre / post / return values + - [ ] mention explicitly, that user has to manage their buffer + - [ ] move special case 'not enough space' to return values / pre / post +- [ ] Description of functions reads nicely - [ ] remove / define abbreviated (make it more explicit) + - [ ] "Writes keyName of `key` into the provided buffer `returnedName` if it is shorter than `maxSize`" +- [ ] `@pre` + - [ ] `key` is a valid Key + - [ ] `returnedName` is a pre-allocated buffer + - [ ] maxSize is the size of `returnedName` +- [ ] `@post` + - [ ] `returnedName` contains the name of the Key + - [ ] `key` is not modified +- [ ] `@invariant` + - [ ] `key` is not modified +- [ ] `@param` for every parameter + - [ ] `returnedName`: pre-allocated buffer to write the key name into +- [ ] `@return` / `@retval` + - [ ] `1`: when only a null-terminator was written + - [ ] `-1`: then -> than + - [ ] `-1`: standardize / change 'keyname' / 'key name' or 'Key name' + - [ ] `-1` check if null pointer case is even still applicable + - [ ] `-1` split into two lines: maxSize / NULL pointer - [ ] `@since` - - [ ] add + - [ ] add - [x] `@ingroup` - [ ] `@see` - - [ ] keyName - - [ ] keyGetUnescapedName - - [ ] keyGetBaseName - - [ ] keyGetNamespace + - [ ] keyName + - [ ] keyGetUnescapedName + - [ ] keyGetBaseName + - [ ] keyGetNamespace ### Naming @@ -59,14 +58,14 @@ [Glossary](/doc/help/elektra-glossary.md) - [x] Function names should neither be too long, nor too short - [ ] Function name should be clear and unambiguous - - [ ] `keyName` vs `keyGetName()` + - [ ] `keyName` vs `keyGetName()` - [ ] Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - - [ ] max - maybe just rename to `bufferSize` + - [ ] max - maybe just rename to `bufferSize` - [ ] Parameter names should neither be too long, nor too short - - [ ] `returnedName` -> `name` / `nameBuffer` + - [ ] `returnedName` -> `name` / `nameBuffer` - [ ] Parameter names should be clear and unambiguous - - [ ] `maxSize` -> `bufferSize` + - [ ] `maxSize` -> `bufferSize` ### Compatibility @@ -95,22 +94,20 @@ ### Memory Management - [ ] Memory Management should be handled by the function wherever possible - - [ ] pass variable and return size instead - - [ ] remove `maxSize` param + - [ ] pass variable and return size instead + - [ ] remove `maxSize` param ### Extensibility - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] nothing is written on maxSize < nameSize (would be fixed with - memory management suggestion from above) + - [ ] nothing is written on maxSize < nameSize (would be fixed with + memory management suggestion from above) ### Tests -- [ ] Function code is fully covered by tests - - Lines 365 / 366 -- [ ] All possible error states are covered by tests - - test empty string +- [ ] Function code is fully covered by tests - Lines 365 / 366 +- [ ] All possible error states are covered by tests - test empty string - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md index d4a171d337b..c29495197ba 100644 --- a/doc/api_review/core/keyGetNameSize.md +++ b/doc/api_review/core/keyGetNameSize.md @@ -16,31 +16,32 @@ (bullet points are in order of appearance) - [ ] First line explains briefly what the function does - - [ ] only describes return value - - [ ] null-termination - - [ ] mit return mergen + - [ ] only describes return value + - [ ] null-termination + - [ ] mit return mergen - [ ] Simple example or snippet how to use the function - - [ ] add + - [ ] add - [ ] Longer description of function containing common use cases - - [ ] better describe common use case - - [ ] example for error case - - [ ] example for empty string + - [ ] better describe common use case + - [ ] example for error case + - [ ] example for empty string - [x] Description of functions reads nicely - [ ] `@pre` - - [ ] add 'Key should be valid' + - [ ] add 'Key should be valid' - [ ] `@post` - - [ ] add 'key doesn't get modified' + - [ ] add 'key doesn't get modified' - [ ] `@invariant` - - [ ] add 'key doesn't get modified' + - [ ] add 'key doesn't get modified' - [ ] `@param` for every parameter - - [ ] 'key object to get the size of the name from' - - [ ] make consistent + - [ ] 'key object to get the size of the name from' + - [ ] make consistent - [ ] `@return` / `@retval` - - [ ] without owner? + - [ ] without owner? - [ ] `@see` - - [ ] add parentheses to keyGetUnescapedNameSize + - [ ] add parentheses to keyGetUnescapedNameSize ### Naming + - Abbreviations used in function names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - [x] Function names should neither be too long, nor too short @@ -87,7 +88,7 @@ - [x] Function code is fully covered by tests - [ ] All possible error states are covered by tests - - [ ] add test case for NULL pointer + - [ ] add test case for NULL pointer - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index 7a7fa629c03..d981abe8986 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -17,29 +17,29 @@ - [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function - - [ ] add + - [ ] add - Longer description of function containing common use cases - All uses cases covered by brief description - [ ] Description of functions reads nicely - - [ ] 'as new string value' seems strange - - [ ] 'private copy' is unclear + - [ ] 'as new string value' seems strange + - [ ] 'private copy' is unclear - [ ] `@pre` - - [ ] add + - [ ] add - [ ] `@post` - - [ ] add - - [ ] string saved as UTF-8 in backend + - [ ] add + - [ ] string saved as UTF-8 in backend - [ ] `@invariant` - - [ ] add -- [ ] `@param` for every parameter - - [ ] 'text string' maybe redundant? + - [ ] add +- [ ] `@param` for every parameter + - [ ] 'text string' maybe redundant? - [x] `@return` / `@retval` -- [ ] `@since` - - [ ] add +- [ ] `@since` + - [ ] add - [x] `@ingroup` - [ ] `@see` - - [ ] split to multiple lines - - [ ] shortly explain differences between `keyString` `keyGetString` - - [ ] add `keySetBinary` ? - - [ ] remove `keyValue`, as it is not related to string + - [ ] split to multiple lines + - [ ] shortly explain differences between `keyString` `keyGetString` + - [ ] add `keySetBinary` ? + - [ ] remove `keyValue`, as it is not related to string ### Naming @@ -50,7 +50,7 @@ - Abbreviations used in parameter names must be defined in the [Glossary](/doc/help/elektra-glossary.md) - [ ] Parameter names should neither be too long, nor too short - - [ ] `newStringValue` - remove Value? + - [ ] `newStringValue` - remove Value? - [x] Parameter names should be clear and unambiguous ### Compatibility @@ -85,9 +85,9 @@ - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] iconv-Plugin - - [ ] UTF-8 - - [ ] Return Value on NULL + - [ ] iconv-Plugin + - [ ] UTF-8 + - [ ] Return Value on NULL ### Tests From 3f998ad3d42cd3cc88fa56b47e2ffc694eaa4855 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 23 Feb 2021 00:16:33 +0100 Subject: [PATCH 19/29] update link to build server --- doc/DESIGN.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 23bdb833792..711c482fbde 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -286,8 +286,8 @@ directly. ## Design Guidelines Checklist -On potential changes of the API/ABI as detected by -[`elektra-icheck`](https://build.libelektra.org/job/elektra-icheck), +On potential changes of the API/ABI as detected by the +[`build server`](https://build.libelektra.org/job/libelektra/job/master/), please make sure the API has been reviewed according to the following 2 checklists: From 7e925fd05a1bdf60ff499e6fa76a5f5ec9a3acda Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 23 Feb 2021 00:20:15 +0100 Subject: [PATCH 20/29] docs: fix autoformatting introduced errors --- doc/api_review/core/keyGetName.md | 14 +++++++++----- doc/api_review/core/keySetString.md | 3 ++- 2 files changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index 0e4d2c62723..265a0cf734d 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -24,7 +24,8 @@ - [ ] maxSize special case move description to pre / post / return values - [ ] mention explicitly, that user has to manage their buffer - [ ] move special case 'not enough space' to return values / pre / post -- [ ] Description of functions reads nicely - [ ] remove / define abbreviated (make it more explicit) +- [ ] Description of functions reads nicely + - [ ] remove / define abbreviated (make it more explicit) - [ ] "Writes keyName of `key` into the provided buffer `returnedName` if it is shorter than `maxSize`" - [ ] `@pre` - [ ] `key` is a valid Key @@ -88,14 +89,15 @@ - [x] Functions should do exactly one thing - [x] Function name has the appropriate prefix -- [ ] Order of signatures in kdb.h.in is the same as Doxygen - wrong order +- [ ] Order of signatures in kdb.h.in is the same as Doxygen + - wrong order - [x] No functions with similar purpose exist ### Memory Management - [ ] Memory Management should be handled by the function wherever possible - [ ] pass variable and return size instead - - [ ] remove `maxSize` param + - [ ] remove `maxSize` param ### Extensibility @@ -106,8 +108,10 @@ ### Tests -- [ ] Function code is fully covered by tests - Lines 365 / 366 -- [ ] All possible error states are covered by tests - test empty string +- [ ] Function code is fully covered by tests + - Lines 365 / 366 +- [ ] All possible error states are covered by tests + - test empty string - All possible enum values are covered by tests - [x] No inconsistencies between tests and documentation diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index d981abe8986..ec34f18bbd8 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -18,7 +18,8 @@ - [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function - [ ] add -- Longer description of function containing common use cases - All uses cases covered by brief description +- Longer description of function containing common use cases + - All uses cases covered by brief description - [ ] Description of functions reads nicely - [ ] 'as new string value' seems strange - [ ] 'private copy' is unclear From 19e81f763b4d60d6a7a6f172ceb15998950e42da Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 23 Feb 2021 00:25:17 +0100 Subject: [PATCH 21/29] docs: reformatting --- doc/api_review/core/keySetString.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index ec34f18bbd8..13febc1ff36 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -18,8 +18,8 @@ - [x] First line explains briefly what the function does - [ ] Simple example or snippet how to use the function - [ ] add -- Longer description of function containing common use cases - - All uses cases covered by brief description +- Longer description of function containing common use cases + - All uses cases covered by brief description - [ ] Description of functions reads nicely - [ ] 'as new string value' seems strange - [ ] 'private copy' is unclear From 43380d2ae29340a712cf59ab2b221d1f464e37e1 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 23 Feb 2021 16:40:52 +0100 Subject: [PATCH 22/29] add shebang to generate reviews script --- scripts/api_review/generate_review_files.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/api_review/generate_review_files.py b/scripts/api_review/generate_review_files.py index 48c8ce6ff2e..88e1cc8a5ef 100644 --- a/scripts/api_review/generate_review_files.py +++ b/scripts/api_review/generate_review_files.py @@ -1,3 +1,5 @@ +#!/usr/bin/env python3 + import re import argparse import sys From 1d68052c6fcf8900792e8b7962b65d6fa85c8e05 Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Tue, 23 Feb 2021 17:01:28 +0100 Subject: [PATCH 23/29] fix spelling of markdown files --- doc/api_review/core/keyDel.md | 2 +- doc/api_review/core/keySetName.md | 2 +- doc/api_review/core/keySetString.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api_review/core/keyDel.md b/doc/api_review/core/keyDel.md index e8bb0ebfeeb..5146572273d 100644 --- a/doc/api_review/core/keyDel.md +++ b/doc/api_review/core/keyDel.md @@ -78,7 +78,7 @@ - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] TBD cannot change behaviour of referenced keys + - [ ] TBD cannot change behavior of referenced keys ### Tests diff --git a/doc/api_review/core/keySetName.md b/doc/api_review/core/keySetName.md index c3b172fbaac..e129991a38e 100644 --- a/doc/api_review/core/keySetName.md +++ b/doc/api_review/core/keySetName.md @@ -81,7 +81,7 @@ - [x] Function is easily extensible, e.g., with flags - [ ] Documentation does not impose limits, that would hinder further extensions - - [ ] behaviour on invalid names + - [ ] behavior on invalid names ### Tests diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index 13febc1ff36..aee0d9d4fd1 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -99,5 +99,5 @@ ## Summary -Behaviour when `newStringValue` is a NULL pointer seems strange +Behavior when `newStringValue` is a NULL pointer seems strange Exact difference keyString keyGetString ? From 7c62fe446e5172dcec08484a7ab3f0ca5caf0a5e Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Wed, 24 Feb 2021 19:17:41 +0100 Subject: [PATCH 24/29] docs: add release notes and whitelist link breaking the build --- doc/news/_preparation_next_release.md | 1 + tests/linkchecker.whitelist | 2 ++ 2 files changed, 3 insertions(+) diff --git a/doc/news/_preparation_next_release.md b/doc/news/_preparation_next_release.md index fe662012b93..64c9df14501 100644 --- a/doc/news/_preparation_next_release.md +++ b/doc/news/_preparation_next_release.md @@ -123,6 +123,7 @@ you up to date with the multi-language support provided by Elektra. - <> - <> - <> +- Added API-Reviews for multiple functions in the public API _(Stefan Hanreich)_ ## Tests diff --git a/tests/linkchecker.whitelist b/tests/linkchecker.whitelist index 29405011383..48a9e7915fe 100644 --- a/tests/linkchecker.whitelist +++ b/tests/linkchecker.whitelist @@ -38,3 +38,5 @@ https://doc.libelektra.org/coverage/master/debian-buster-full http://mingw.org http://api.zeromq.org/4-2:zmq-ipc http://api.zeromq.org/4-2:zmq-tcp +# wrongly detected as broken, even though its online +https://www.sciencedaily.com/releases/2005/11/051103080801.htm From eaa68b68f1359cd20d48d7c881f25febcf31c4ea Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Thu, 25 Feb 2021 19:57:17 +0100 Subject: [PATCH 25/29] doc: add section for issues unrelated to function - link templates in Design.MD --- doc/DESIGN.md | 73 ++----------------- doc/api_review/core/kdbClose.md | 2 + doc/api_review/core/kdbEnsure.md | 2 + doc/api_review/core/kdbGet.md | 2 + doc/api_review/core/kdbOpen.md | 2 + doc/api_review/core/kdbSet.md | 2 + doc/api_review/core/keyAddBaseName.md | 2 + doc/api_review/core/keyAddName.md | 2 + doc/api_review/core/keyBaseName.md | 2 + doc/api_review/core/keyClear.md | 2 + doc/api_review/core/keyCmp.md | 2 + doc/api_review/core/keyCopy.md | 2 + doc/api_review/core/keyCopyAllMeta.md | 2 + doc/api_review/core/keyCopyMeta.md | 2 + doc/api_review/core/keyCurrentMeta.md | 2 + doc/api_review/core/keyDecRef.md | 2 + doc/api_review/core/keyDel.md | 2 + doc/api_review/core/keyDup.md | 2 + doc/api_review/core/keyGetBaseName.md | 2 + doc/api_review/core/keyGetBaseNameSize.md | 2 + doc/api_review/core/keyGetBinary.md | 2 + doc/api_review/core/keyGetMeta.md | 2 + doc/api_review/core/keyGetName.md | 2 + doc/api_review/core/keyGetNameSize.md | 2 + doc/api_review/core/keyGetNamespace.md | 2 + doc/api_review/core/keyGetRef.md | 2 + doc/api_review/core/keyGetString.md | 2 + .../core/keyGetUnescapedNameSize.md | 2 + doc/api_review/core/keyGetValueSize.md | 2 + doc/api_review/core/keyIncRef.md | 2 + doc/api_review/core/keyIsBelow.md | 2 + doc/api_review/core/keyIsBelowOrSame.md | 2 + doc/api_review/core/keyIsBinary.md | 2 + doc/api_review/core/keyIsDirectlyBelow.md | 2 + doc/api_review/core/keyIsLocked.md | 2 + doc/api_review/core/keyIsString.md | 2 + doc/api_review/core/keyLock.md | 2 + doc/api_review/core/keyMeta.md | 2 + doc/api_review/core/keyName.md | 2 + doc/api_review/core/keyNeedSync.md | 2 + doc/api_review/core/keyNew.md | 2 + doc/api_review/core/keyNextMeta.md | 2 + doc/api_review/core/keyRewindMeta.md | 2 + doc/api_review/core/keySetBaseName.md | 2 + doc/api_review/core/keySetBinary.md | 2 + doc/api_review/core/keySetMeta.md | 2 + doc/api_review/core/keySetName.md | 2 + doc/api_review/core/keySetNamespace.md | 2 + doc/api_review/core/keySetString.md | 3 + doc/api_review/core/keyString.md | 2 + doc/api_review/core/keyUnescapedName.md | 2 + doc/api_review/core/keyVNew.md | 2 + doc/api_review/core/keyValue.md | 2 + doc/api_review/core/ksAppend.md | 2 + doc/api_review/core/ksAppendKey.md | 2 + doc/api_review/core/ksAtCursor.md | 2 + doc/api_review/core/ksClear.md | 2 + doc/api_review/core/ksCopy.md | 2 + doc/api_review/core/ksCurrent.md | 2 + doc/api_review/core/ksCut.md | 2 + doc/api_review/core/ksDel.md | 2 + doc/api_review/core/ksDup.md | 2 + doc/api_review/core/ksGetCursor.md | 2 + doc/api_review/core/ksGetSize.md | 2 + doc/api_review/core/ksHead.md | 2 + doc/api_review/core/ksLookup.md | 2 + doc/api_review/core/ksLookupByName.md | 2 + doc/api_review/core/ksNeedSync.md | 2 + doc/api_review/core/ksNew.md | 2 + doc/api_review/core/ksNext.md | 2 + doc/api_review/core/ksPop.md | 2 + doc/api_review/core/ksRewind.md | 2 + doc/api_review/core/ksSetCursor.md | 2 + doc/api_review/core/ksTail.md | 2 + doc/api_review/core/ksVNew.md | 2 + scripts/api_review/template.c.md | 2 + scripts/api_review/template.java.md | 2 + scripts/api_review/template.rs.md | 2 + 78 files changed, 160 insertions(+), 68 deletions(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 711c482fbde..01500a89992 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -315,72 +315,9 @@ following 2 checklists: ## Checklist for each function -### Documentation - -- [ ] Change is mentioned in the Compatibility section of the release notes -- [ ] No inconsistencies between documentation and tests -- [ ] Proper Documentation of thread-safety of function -- [ ] All possible error states are documented -- [ ] Configuration flags are documented - -#### Doxygen - -- [ ] Precondition / Postcondition / Invariant -- [ ] `@retval` -- [ ] `@see` -- [ ] `@since` -- [ ] `@ingroup` -- [ ] there is at least one example or snippet how to use the function - -### Naming - -- [ ] Abbreviations used in parameter names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Abbreviations used in function names must be defined in the - [Glossary](/doc/help/elektra-glossary.md) -- [ ] Parameter names should neither be too long, nor too short -- [ ] Function names should neither be too long, nor too short -- [ ] Function name should be clear and unambiguous -- [ ] Parameter names should be clear and unambiguous +There are several checklists for functions, depending on the language in which +the function is written: -### Compatibility - -- [ ] [Symbol versioning](/doc/dev/symbol-versioning.md) - is correct for breaking changes -- [ ] ABI/API changes are forward-compatible (breaking backwards-compatibility - to add additional symbols is fine) - -### Parameter & Return Types - -- [ ] Functions should return the most specific type possible -- [ ] Functions should require the most general type possible -- [ ] Functions should use constant types instead of boolean types - wherever sensible -- [ ] Wherever possible, function parameters should be `const` -- [ ] Wherever possible, return types should be `const` -- [ ] Functions should have the least amount of parameters feasible - -### Structural Clarity - -- [ ] Functions should do exactly one thing -- [ ] Functions should have no side effects -- [ ] Configuration options are named constants -- [ ] Function belongs to appropriate group - -### Memory Management - -- [ ] Memory Management should be handled by the function wherever possible -- [ ] Every memory allocation should be documented - -### Extensibility - -- [ ] Function is easily extensible with function flags (constants) -- [ ] Documentation does not impose limits, that would hinder further extensions - -### Tests - -- [ ] Added functions are fully covered by tests -- [ ] All possible error states are covered by tests -- [ ] All possible configuration options are covered by tests -- [ ] Function body has full test coverage -- [ ] No inconsistencies between tests and documentation +- [C](/scripts/api_review/template.c.md) +- [Rust](/scripts/api_review/template.rs.md) +- [Java](/scripts/api_review/template.java.md) \ No newline at end of file diff --git a/doc/api_review/core/kdbClose.md b/doc/api_review/core/kdbClose.md index 289bca96823..a7c3db21207 100644 --- a/doc/api_review/core/kdbClose.md +++ b/doc/api_review/core/kdbClose.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/kdbEnsure.md b/doc/api_review/core/kdbEnsure.md index 9f0cbed068c..1da4d18dbf9 100644 --- a/doc/api_review/core/kdbEnsure.md +++ b/doc/api_review/core/kdbEnsure.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/kdbGet.md b/doc/api_review/core/kdbGet.md index 41f7a2818ed..4fee044f220 100644 --- a/doc/api_review/core/kdbGet.md +++ b/doc/api_review/core/kdbGet.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/kdbOpen.md b/doc/api_review/core/kdbOpen.md index ef5331c910d..1a294f3c224 100644 --- a/doc/api_review/core/kdbOpen.md +++ b/doc/api_review/core/kdbOpen.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/kdbSet.md b/doc/api_review/core/kdbSet.md index 4dcdb646ac1..8f8ea7a6cc8 100644 --- a/doc/api_review/core/kdbSet.md +++ b/doc/api_review/core/kdbSet.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyAddBaseName.md b/doc/api_review/core/keyAddBaseName.md index 193c8141d31..75a2a304943 100644 --- a/doc/api_review/core/keyAddBaseName.md +++ b/doc/api_review/core/keyAddBaseName.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyAddName.md b/doc/api_review/core/keyAddName.md index 24f64015af3..820b32ba2d2 100644 --- a/doc/api_review/core/keyAddName.md +++ b/doc/api_review/core/keyAddName.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyBaseName.md b/doc/api_review/core/keyBaseName.md index 6ab89df2292..2b14923dab8 100644 --- a/doc/api_review/core/keyBaseName.md +++ b/doc/api_review/core/keyBaseName.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyClear.md b/doc/api_review/core/keyClear.md index c9e93789b2a..6f5b19a0e4d 100644 --- a/doc/api_review/core/keyClear.md +++ b/doc/api_review/core/keyClear.md @@ -90,3 +90,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyCmp.md b/doc/api_review/core/keyCmp.md index f0bb0f00a8e..771312ff7a2 100644 --- a/doc/api_review/core/keyCmp.md +++ b/doc/api_review/core/keyCmp.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyCopy.md b/doc/api_review/core/keyCopy.md index 2c5c88fd78e..dae3aca84ba 100644 --- a/doc/api_review/core/keyCopy.md +++ b/doc/api_review/core/keyCopy.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyCopyAllMeta.md b/doc/api_review/core/keyCopyAllMeta.md index 2f8b04434b7..e80b033de57 100644 --- a/doc/api_review/core/keyCopyAllMeta.md +++ b/doc/api_review/core/keyCopyAllMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyCopyMeta.md b/doc/api_review/core/keyCopyMeta.md index c747a5b8406..84f888937ea 100644 --- a/doc/api_review/core/keyCopyMeta.md +++ b/doc/api_review/core/keyCopyMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyCurrentMeta.md b/doc/api_review/core/keyCurrentMeta.md index d5107ba6388..1ebc2bfff2e 100644 --- a/doc/api_review/core/keyCurrentMeta.md +++ b/doc/api_review/core/keyCurrentMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyDecRef.md b/doc/api_review/core/keyDecRef.md index f73f987782a..58b4b320e73 100644 --- a/doc/api_review/core/keyDecRef.md +++ b/doc/api_review/core/keyDecRef.md @@ -92,3 +92,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyDel.md b/doc/api_review/core/keyDel.md index 5146572273d..c37a26770bf 100644 --- a/doc/api_review/core/keyDel.md +++ b/doc/api_review/core/keyDel.md @@ -88,3 +88,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyDup.md b/doc/api_review/core/keyDup.md index 052ad3f6620..83bfea22dd4 100644 --- a/doc/api_review/core/keyDup.md +++ b/doc/api_review/core/keyDup.md @@ -93,3 +93,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetBaseName.md b/doc/api_review/core/keyGetBaseName.md index 03eb6c1f48a..f11c6111f3d 100644 --- a/doc/api_review/core/keyGetBaseName.md +++ b/doc/api_review/core/keyGetBaseName.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetBaseNameSize.md b/doc/api_review/core/keyGetBaseNameSize.md index c34e077e213..80108582224 100644 --- a/doc/api_review/core/keyGetBaseNameSize.md +++ b/doc/api_review/core/keyGetBaseNameSize.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetBinary.md b/doc/api_review/core/keyGetBinary.md index d2ccc83f9ee..656f4212580 100644 --- a/doc/api_review/core/keyGetBinary.md +++ b/doc/api_review/core/keyGetBinary.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetMeta.md b/doc/api_review/core/keyGetMeta.md index e402848ce17..53d0f0aad47 100644 --- a/doc/api_review/core/keyGetMeta.md +++ b/doc/api_review/core/keyGetMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetName.md b/doc/api_review/core/keyGetName.md index 265a0cf734d..824a4a5a4a8 100644 --- a/doc/api_review/core/keyGetName.md +++ b/doc/api_review/core/keyGetName.md @@ -118,3 +118,5 @@ ## Summary Different error codes for different errors + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetNameSize.md b/doc/api_review/core/keyGetNameSize.md index c29495197ba..554d512860c 100644 --- a/doc/api_review/core/keyGetNameSize.md +++ b/doc/api_review/core/keyGetNameSize.md @@ -95,3 +95,5 @@ ## Summary try splitting ifs to two lines, for better coverage reports + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetNamespace.md b/doc/api_review/core/keyGetNamespace.md index ea4cc7bdc5e..7ce4c7029f2 100644 --- a/doc/api_review/core/keyGetNamespace.md +++ b/doc/api_review/core/keyGetNamespace.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetRef.md b/doc/api_review/core/keyGetRef.md index f21bf1a4e72..05053ee3981 100644 --- a/doc/api_review/core/keyGetRef.md +++ b/doc/api_review/core/keyGetRef.md @@ -87,3 +87,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetString.md b/doc/api_review/core/keyGetString.md index 78302d60259..ee93645f17c 100644 --- a/doc/api_review/core/keyGetString.md +++ b/doc/api_review/core/keyGetString.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetUnescapedNameSize.md b/doc/api_review/core/keyGetUnescapedNameSize.md index fb053a53653..a259ab9deb8 100644 --- a/doc/api_review/core/keyGetUnescapedNameSize.md +++ b/doc/api_review/core/keyGetUnescapedNameSize.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyGetValueSize.md b/doc/api_review/core/keyGetValueSize.md index 7a6d841cc51..9a7cfd0e816 100644 --- a/doc/api_review/core/keyGetValueSize.md +++ b/doc/api_review/core/keyGetValueSize.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyIncRef.md b/doc/api_review/core/keyIncRef.md index 4d1b726f03d..41d59fc1a40 100644 --- a/doc/api_review/core/keyIncRef.md +++ b/doc/api_review/core/keyIncRef.md @@ -90,3 +90,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyIsBelow.md b/doc/api_review/core/keyIsBelow.md index cf21897f971..cf569154595 100644 --- a/doc/api_review/core/keyIsBelow.md +++ b/doc/api_review/core/keyIsBelow.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyIsBelowOrSame.md b/doc/api_review/core/keyIsBelowOrSame.md index 7db7d73e60b..44a2eae7a06 100644 --- a/doc/api_review/core/keyIsBelowOrSame.md +++ b/doc/api_review/core/keyIsBelowOrSame.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyIsBinary.md b/doc/api_review/core/keyIsBinary.md index aff764a4914..ce4fc17c02b 100644 --- a/doc/api_review/core/keyIsBinary.md +++ b/doc/api_review/core/keyIsBinary.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyIsDirectlyBelow.md b/doc/api_review/core/keyIsDirectlyBelow.md index a1dc87f1566..53b57cc5df1 100644 --- a/doc/api_review/core/keyIsDirectlyBelow.md +++ b/doc/api_review/core/keyIsDirectlyBelow.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyIsLocked.md b/doc/api_review/core/keyIsLocked.md index d5f1bd271e5..3309b67b3ac 100644 --- a/doc/api_review/core/keyIsLocked.md +++ b/doc/api_review/core/keyIsLocked.md @@ -90,3 +90,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyIsString.md b/doc/api_review/core/keyIsString.md index f763782ce2d..5fdd496267f 100644 --- a/doc/api_review/core/keyIsString.md +++ b/doc/api_review/core/keyIsString.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyLock.md b/doc/api_review/core/keyLock.md index d5950eb1638..74480edb641 100644 --- a/doc/api_review/core/keyLock.md +++ b/doc/api_review/core/keyLock.md @@ -96,3 +96,5 @@ ## Summary Also check return values of function in tests + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyMeta.md b/doc/api_review/core/keyMeta.md index 32d75bbb9e5..002cfd69c33 100644 --- a/doc/api_review/core/keyMeta.md +++ b/doc/api_review/core/keyMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyName.md b/doc/api_review/core/keyName.md index 361a68f39f8..3e4bd72e8d3 100644 --- a/doc/api_review/core/keyName.md +++ b/doc/api_review/core/keyName.md @@ -88,3 +88,5 @@ - [x] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyNeedSync.md b/doc/api_review/core/keyNeedSync.md index 20831fc08ff..4e982c7473d 100644 --- a/doc/api_review/core/keyNeedSync.md +++ b/doc/api_review/core/keyNeedSync.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyNew.md b/doc/api_review/core/keyNew.md index 4c348f9a1e4..dd815f90b1f 100644 --- a/doc/api_review/core/keyNew.md +++ b/doc/api_review/core/keyNew.md @@ -94,3 +94,5 @@ - [ ] same as above with `keyNew(0)` ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyNextMeta.md b/doc/api_review/core/keyNextMeta.md index 2456ac73484..c45430c0ab4 100644 --- a/doc/api_review/core/keyNextMeta.md +++ b/doc/api_review/core/keyNextMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyRewindMeta.md b/doc/api_review/core/keyRewindMeta.md index df9a88febd1..b4eb6bd1e9a 100644 --- a/doc/api_review/core/keyRewindMeta.md +++ b/doc/api_review/core/keyRewindMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keySetBaseName.md b/doc/api_review/core/keySetBaseName.md index 5f154aceb5c..fc6fcfc8d85 100644 --- a/doc/api_review/core/keySetBaseName.md +++ b/doc/api_review/core/keySetBaseName.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keySetBinary.md b/doc/api_review/core/keySetBinary.md index d4c45befd77..9378b969615 100644 --- a/doc/api_review/core/keySetBinary.md +++ b/doc/api_review/core/keySetBinary.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keySetMeta.md b/doc/api_review/core/keySetMeta.md index a60dd973fe8..d6f42b9a1fe 100644 --- a/doc/api_review/core/keySetMeta.md +++ b/doc/api_review/core/keySetMeta.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keySetName.md b/doc/api_review/core/keySetName.md index e129991a38e..79e49c2d645 100644 --- a/doc/api_review/core/keySetName.md +++ b/doc/api_review/core/keySetName.md @@ -101,3 +101,5 @@ - [ ] Documentations should include stripping trailing `/` ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keySetNamespace.md b/doc/api_review/core/keySetNamespace.md index 7b9b1722882..56280657e73 100644 --- a/doc/api_review/core/keySetNamespace.md +++ b/doc/api_review/core/keySetNamespace.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keySetString.md b/doc/api_review/core/keySetString.md index aee0d9d4fd1..e0d57b4c0df 100644 --- a/doc/api_review/core/keySetString.md +++ b/doc/api_review/core/keySetString.md @@ -100,4 +100,7 @@ ## Summary Behavior when `newStringValue` is a NULL pointer seems strange + +## Other Issues discovered (unrelated to function) + Exact difference keyString keyGetString ? diff --git a/doc/api_review/core/keyString.md b/doc/api_review/core/keyString.md index 8be71dc58f9..9cc4d4a9c61 100644 --- a/doc/api_review/core/keyString.md +++ b/doc/api_review/core/keyString.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyUnescapedName.md b/doc/api_review/core/keyUnescapedName.md index 043c799400c..d0650a0dace 100644 --- a/doc/api_review/core/keyUnescapedName.md +++ b/doc/api_review/core/keyUnescapedName.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyVNew.md b/doc/api_review/core/keyVNew.md index 23cbbf62472..0d29f519c89 100644 --- a/doc/api_review/core/keyVNew.md +++ b/doc/api_review/core/keyVNew.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/keyValue.md b/doc/api_review/core/keyValue.md index 00e244687fc..2b934a03a9b 100644 --- a/doc/api_review/core/keyValue.md +++ b/doc/api_review/core/keyValue.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksAppend.md b/doc/api_review/core/ksAppend.md index 63c5f6c3471..9a570933ea5 100644 --- a/doc/api_review/core/ksAppend.md +++ b/doc/api_review/core/ksAppend.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksAppendKey.md b/doc/api_review/core/ksAppendKey.md index b5e1a847a68..1df84961179 100644 --- a/doc/api_review/core/ksAppendKey.md +++ b/doc/api_review/core/ksAppendKey.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksAtCursor.md b/doc/api_review/core/ksAtCursor.md index d7acdeb5752..8363c94a074 100644 --- a/doc/api_review/core/ksAtCursor.md +++ b/doc/api_review/core/ksAtCursor.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksClear.md b/doc/api_review/core/ksClear.md index 045213764f7..0791b9a3a6f 100644 --- a/doc/api_review/core/ksClear.md +++ b/doc/api_review/core/ksClear.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksCopy.md b/doc/api_review/core/ksCopy.md index 3499d559d1b..8390e9dc785 100644 --- a/doc/api_review/core/ksCopy.md +++ b/doc/api_review/core/ksCopy.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksCurrent.md b/doc/api_review/core/ksCurrent.md index 30ee70a4ccf..b36a672c35c 100644 --- a/doc/api_review/core/ksCurrent.md +++ b/doc/api_review/core/ksCurrent.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksCut.md b/doc/api_review/core/ksCut.md index 63bcff19b57..265bd9d03ea 100644 --- a/doc/api_review/core/ksCut.md +++ b/doc/api_review/core/ksCut.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksDel.md b/doc/api_review/core/ksDel.md index 70412cce9f6..6db62a204e1 100644 --- a/doc/api_review/core/ksDel.md +++ b/doc/api_review/core/ksDel.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksDup.md b/doc/api_review/core/ksDup.md index 757074ee945..a5b9270b857 100644 --- a/doc/api_review/core/ksDup.md +++ b/doc/api_review/core/ksDup.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksGetCursor.md b/doc/api_review/core/ksGetCursor.md index 7e6e6a3ce26..38a1aa078b3 100644 --- a/doc/api_review/core/ksGetCursor.md +++ b/doc/api_review/core/ksGetCursor.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksGetSize.md b/doc/api_review/core/ksGetSize.md index 8cb08a3b84c..5c61251757b 100644 --- a/doc/api_review/core/ksGetSize.md +++ b/doc/api_review/core/ksGetSize.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksHead.md b/doc/api_review/core/ksHead.md index 64744c62833..4db05918bba 100644 --- a/doc/api_review/core/ksHead.md +++ b/doc/api_review/core/ksHead.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksLookup.md b/doc/api_review/core/ksLookup.md index 1c8fc81009a..c6ba37ecd76 100644 --- a/doc/api_review/core/ksLookup.md +++ b/doc/api_review/core/ksLookup.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksLookupByName.md b/doc/api_review/core/ksLookupByName.md index 143b6ed15bc..d985f564499 100644 --- a/doc/api_review/core/ksLookupByName.md +++ b/doc/api_review/core/ksLookupByName.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksNeedSync.md b/doc/api_review/core/ksNeedSync.md index 3b3a339b85c..57959ef12b4 100644 --- a/doc/api_review/core/ksNeedSync.md +++ b/doc/api_review/core/ksNeedSync.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksNew.md b/doc/api_review/core/ksNew.md index 907820b207f..1476f7d7cad 100644 --- a/doc/api_review/core/ksNew.md +++ b/doc/api_review/core/ksNew.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksNext.md b/doc/api_review/core/ksNext.md index c5d1b0782ef..6ca5f7e2a8a 100644 --- a/doc/api_review/core/ksNext.md +++ b/doc/api_review/core/ksNext.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksPop.md b/doc/api_review/core/ksPop.md index 8407e736ee6..50bd5d7a528 100644 --- a/doc/api_review/core/ksPop.md +++ b/doc/api_review/core/ksPop.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksRewind.md b/doc/api_review/core/ksRewind.md index 8e3bb92e7f1..cda382b2e18 100644 --- a/doc/api_review/core/ksRewind.md +++ b/doc/api_review/core/ksRewind.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksSetCursor.md b/doc/api_review/core/ksSetCursor.md index 79d80a84089..cd7f4ae9ba6 100644 --- a/doc/api_review/core/ksSetCursor.md +++ b/doc/api_review/core/ksSetCursor.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksTail.md b/doc/api_review/core/ksTail.md index 9e934b9c6fe..7d8989283a1 100644 --- a/doc/api_review/core/ksTail.md +++ b/doc/api_review/core/ksTail.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/doc/api_review/core/ksVNew.md b/doc/api_review/core/ksVNew.md index 52fc9a19f66..32bb00dc5fa 100644 --- a/doc/api_review/core/ksVNew.md +++ b/doc/api_review/core/ksVNew.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/scripts/api_review/template.c.md b/scripts/api_review/template.c.md index 2305e51fb70..dbb4e3dea12 100644 --- a/scripts/api_review/template.c.md +++ b/scripts/api_review/template.c.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/scripts/api_review/template.java.md b/scripts/api_review/template.java.md index ca06eb867c6..695ac1a8404 100644 --- a/scripts/api_review/template.java.md +++ b/scripts/api_review/template.java.md @@ -79,3 +79,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) diff --git a/scripts/api_review/template.rs.md b/scripts/api_review/template.rs.md index 47b431b2ad1..097f12e96c7 100644 --- a/scripts/api_review/template.rs.md +++ b/scripts/api_review/template.rs.md @@ -78,3 +78,5 @@ - [ ] No inconsistencies between tests and documentation ## Summary + +## Other Issues discovered (unrelated to function) From 4e6bce21f6470ff4a84f3d58d32abb28b2a4f69c Mon Sep 17 00:00:00 2001 From: Stefan Hanreich Date: Thu, 25 Feb 2021 20:03:48 +0100 Subject: [PATCH 26/29] doc: add newline at bottom to DESIGN.md --- doc/DESIGN.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/DESIGN.md b/doc/DESIGN.md index 01500a89992..5add1b66164 100644 --- a/doc/DESIGN.md +++ b/doc/DESIGN.md @@ -320,4 +320,4 @@ the function is written: - [C](/scripts/api_review/template.c.md) - [Rust](/scripts/api_review/template.rs.md) -- [Java](/scripts/api_review/template.java.md) \ No newline at end of file +- [Java](/scripts/api_review/template.java.md) From 9f46c08b799863cdabd59ad96d580137c109dfff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihael=20Pranji=C4=87?= Date: Thu, 25 Feb 2021 23:48:41 +0100 Subject: [PATCH 27/29] Update doc/api_review/README.md Co-authored-by: markus2330 --- doc/api_review/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api_review/README.md b/doc/api_review/README.md index 7e257c5121e..80f92f7c749 100644 --- a/doc/api_review/README.md +++ b/doc/api_review/README.md @@ -12,7 +12,7 @@ every unfulfilled point a short explanation has to be given why the reviewer thinks the function does not fulfill the respective bullet point. This is done simply by providing a short description of the issue below the respective bullet point. After the review has been completed, the reviewer creates an -issue for every unfulfilled bullet point so it can be fixed by the Elektra team. +issue for every unfulfilled bullet point so it can be fixed by the Elektra Initiative. ## Checklist Legend From 969d3a44a44f025712a62da052e5193b53362e4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihael=20Pranji=C4=87?= Date: Thu, 25 Feb 2021 23:48:57 +0100 Subject: [PATCH 28/29] Update doc/api_review/README.md Co-authored-by: markus2330 --- doc/api_review/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api_review/README.md b/doc/api_review/README.md index 80f92f7c749..ad57d963649 100644 --- a/doc/api_review/README.md +++ b/doc/api_review/README.md @@ -1,6 +1,6 @@ # Elektra API Review -This folder contains all API design reviews conducted on the Elektra library. +This folder contains all API design reviews conducted on LibElektra. Below you can find a short description of the review process. ## Review Process From 0b91a9e46489d7a8a556e4de8957663d8b56bbbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihael=20Pranji=C4=87?= Date: Thu, 25 Feb 2021 23:50:13 +0100 Subject: [PATCH 29/29] Update scripts/api_review/generate_review_files.py --- scripts/api_review/generate_review_files.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/api_review/generate_review_files.py b/scripts/api_review/generate_review_files.py index 88e1cc8a5ef..635fd0fa236 100644 --- a/scripts/api_review/generate_review_files.py +++ b/scripts/api_review/generate_review_files.py @@ -83,4 +83,4 @@ def get_method_name(method): with open(get_file_name(method_name), 'w') as output_file: output_file.write( template.format(signature = method, name = method_name) - ) \ No newline at end of file + )