.TH "doc_api_review_core_keyCopy_md" 3elektra "Mon Jan 9 2023" "Version 0.9.11" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
doc_api_review_core_keyCopy_md \- keyCopy 
invariants?
.PP
.IP "\(bu" 2
start = 2021-02-13 12:00
.IP "\(bu" 2
end = 2021-02-13 13:10
.IP "\(bu" 2
moderator = Stefan Hanreich stefanhani@gmail.com
.IP "\(bu" 2
reviewer = Markus Raab markus@libelektra.org
.PP
.SH "Signature"
.PP
\fCint keyCopy(Key *dest, const Key *source);\fP
.SH "Checklist"
.PP
.SS "Doxygen"
.IP "\(bu" 2
[ ] first line explains briefly what the function does 
.br
.IP "  \(bu" 4
[x] Clear -> clear 
.br

.IP "  \(bu" 4
[x] do not instantly reference \fCkeyDup\fP
.PP

.IP "\(bu" 2
[ ] \fC@see\fP 
.br
.IP "  \(bu" 4
[x] add \fC@see\fP for \fCkeyDup\fP
.PP

.IP "\(bu" 2
[ ] \fC@since\fP (optional: for after 1\&.0\&.0) 
.br
.IP "  \(bu" 4
[x] add \fC@since\fP 0\&.9\&.5
.PP

.IP "\(bu" 2
[x] \fC@ingroup\fP
.IP "\(bu" 2
[ ] \fC@retval\fP 
.br
.IP "  \(bu" 4
[x] use retval instead of return (see snippet below)
.PP

.IP "\(bu" 2
[ ] good example or snippet how to use the function 
.br
.IP "  \(bu" 4
[ ] move example to \fCkeyDup\fP
.PP

.IP "\(bu" 2
[ ] simple examples go first 
.br
.IP "  \(bu" 4
[x] move simple example to the top
.PP

.IP "\(bu" 2
[ ] Precondition 
.br
.IP "  \(bu" 4
[x] add precondition (valid key values) 
.br

.IP "  \(bu" 4
[x] 
.PP
\fBPrecondition\fP
.RS 4
dest must be a valid Key (created with keyNew) 
.br
.RE
.PP

.IP "  \(bu" 4
[x] 
.PP
\fBPrecondition\fP
.RS 4
source must be a valid Key or NULL
.RE
.PP

.PP

.IP "\(bu" 2
[ ] Postcondition 
.br
.IP "  \(bu" 4
[x] add postcondition 
.br

.IP "  \(bu" 4
[x] 
.PP
\fBPostcondition\fP
.RS 4
Value is written to key dest
.RE
.PP

.PP

.IP "\(bu" 2
[ ] Invariant 
.br
.IP "  \(bu" 4
[x] add invariant 
.br

.IP "  \(bu" 4
[x] Key name stays valid (document at struct) 
.br

.IP "  \(bu" 4
[x] Key name stays valid until delete
.PP

.IP "\(bu" 2
[ ] \fC@param\fP for every parameter 
.br
.IP "  \(bu" 4
[x] better describe flags (|)
.PP
.PP
invariants?
.PP
.PP
.PP
.nf
@retval dest
@retval NULL in case of error
.fi
.PP
.SS "Naming"
.IP "\(bu" 2
[x] Abbreviations used in function names must be defined in the \fBGlossary\fP src/libs/elektra/symbols\&.map
.IP "\(bu" 2
[x] Function names should neither be too long, nor too short
.IP "\(bu" 2
[x] Function name should be clear and unambiguous
.IP "\(bu" 2
[ ] Abbreviations used in parameter names must be defined in the \fBGlossary\fP 
.br
.IP "  \(bu" 4
[x] add dest to glossary - maybe rename dest to destination?
.PP

.IP "\(bu" 2
[x] Parameter names should neither be too long, nor too short
.IP "\(bu" 2
[x] Parameter names should be clear and unambiguous
.PP
.SS "Compatibility"
.IP "\(bu" 2
[x] ABI/API changes are forward-compatible (breaking backwards-compatibility to add additional symbols is fine)
.PP
.SS "Parameter & Return Types"
.IP "\(bu" 2
Functions should return the most specific type possible
.IP "\(bu" 2
Functions should require the most general type possible
.IP "\(bu" 2
[x] Function parameters should use enum types instead of boolean types wherever sensible
.IP "\(bu" 2
[x] Wherever possible, function parameters should be \fCconst\fP
.IP "\(bu" 2
[x] Wherever possible, return types should be \fCconst\fP
.IP "\(bu" 2
[x] Functions should have the least amount of parameters feasible
.PP
.SS "Structural Clarity"
.IP "\(bu" 2
[ ] Functions should do exactly one thing 
.br
.IP "  \(bu" 4
[x] remove keySetName keySetRaw ksClear functionality from keyCopy?
.PP

.IP "\(bu" 2
[x] Function name has the appropriate prefix
.IP "\(bu" 2
[x] Signature in kdb\&.h\&.in has same order as Doxygen docu
.IP "\(bu" 2
[ ] No functions with similar purpose exist 
.br
.IP "  \(bu" 4
[x] keyCopyAllMeta
.PP

.PP
.SS "Memory Management"
.IP "\(bu" 2
[x] Memory Management should be handled by the function wherever possible
.PP
.SS "Extensibility"
.IP "\(bu" 2
[x] Function is easily extensible, e\&.g\&., with flags
.IP "\(bu" 2
[ ] Documentation does not impose limits, that would hinder further extensions 
.br
.IP "  \(bu" 4
[x] KEY_CP_ALL equivalent to KEY_CP_NAME | KEY_CP_VALUE | KEY_CP_META
.PP

.PP
.SS "Tests"
.IP "\(bu" 2
[ ] Added functions are fully covered by tests https://doc.libelektra.org/coverage/master/debian-buster-full/src/libs/elektra/key.c.gcov.html
.IP "\(bu" 2
[ ] All possible error states are covered by tests and documented
.IP "\(bu" 2
[ ] All possible enum values are covered by tests 
.br
.IP "  \(bu" 4
[x] use flags other than KEY_CP_ALL
.PP

.IP "\(bu" 2
[ ] No inconsistencies between tests and documentation
.IP "\(bu" 2
[ ] Functions should have no side effects (idempotency)
.PP
.SH "Summary"
.PP
.SH "Other Issues discovered (unrelated to function)"
.PP