libk  Check-in [112ee76a31]

Modified libk.md from [ff7e1c7779] to [20f3e7f305].

   215    215   every module has a `cond` type (e.g. `kscond` for `kstr` or `kconf_cond` for `kconf`). this is an enumeration type that represents every possible error a module can return, and every `cond` type obeys a number of invariants (in addition to the usual namespacing rules:
   216    216   
   217    217   1. every member of a cond type has a globally unique integer value. this means that `kscond_ok` has an integer value is not equal to `kmcond_ok`.
   218    218   2. every member of a cond type has a member `kmcond_ok` which represents success. this member's integer value is always an exact multiple of the "module offset", the number of condition values allocated to each module (currently `0x7F`).
   219    219   3. the `kokay()` function, defined in `kcore`, when called on a member of a `cond` type will return true if that member represents total success and false otherwise.
   220    220   4. every cond type has a value `*cond_fail`, for instance `kconf_cond_fail`. if a condition is greater than or equal to its module's `fail` value, it represents a total failure. if it is lesser than the fail value, it represents either success, partial success, or some other condition that does not equate to total failure.
   221    221   
   222         -the reason each error value is unique is that this allows us to map every single condition code unambiguously to an error message. a forthcoming `kcore` function will do exactly that and produce an error string that can be displayed to a user or for debugging purposes. another useful property is that each integer value has at most only one possible meaning in the context of error codes, allowing for centralized error handling - a `kscond` and a `kmcond` can both be turned into an `int` without loss of information; and e.g. `kscond_fail` != `kmcond_fail` != `kconf_cond_fail`.
          222  +the reason each error value is unique is that this allows us to map every single condition code unambiguously to an error message. a forthcoming `kcore` function will do exactly that and produce an error string that can be displayed to a user or for debugging purposes. another useful property is that each integer value has at most only one possible meaning in the context of error codes, allowing for centralized error handling - a `kscond` and a `kmcond` can both be turned into an `int` without loss of information, and e.g. `kscond_fail` != `kmcond_fail` != `kconf_cond_fail`.
   223    223   
   224    224   this is particularly useful as C does not have exceptions, and thus the only viable error-handling mechanisms are early-exit and early-return; any `cond` value can be propagated up the function stack without losing its unique meaning.
   225    225   
   226    226   the value of each condition code is determined at compile time.
   227    227    
   228    228   # authors
   229    229