From 2fca68e18e46e35bcfb960aa1c33eb0ba6eb2f9d Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Tue, 16 Mar 2021 22:54:43 -0500 Subject: [PATCH] Update: add documentation about return codes. --- documents/return_codes.txt | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 documents/return_codes.txt diff --git a/documents/return_codes.txt b/documents/return_codes.txt new file mode 100644 index 0000000..4a386bb --- /dev/null +++ b/documents/return_codes.txt @@ -0,0 +1,37 @@ +# fss-0002 + +Implicit Return Types for f_status_t: + When f_status_t is used as the return type, there are a common set of status codes that should always be expected as a possible return value. + These are implicit expectations even if they are not explicitly documented. + Any function that doesn't support these must document the exceptional state. + + F_failure\: + This may be returned for any general error. + This is often used as the failsafe error code so that an error code of some sort is always returned on error. + + F_parameter\: + This is always potentially returned for any function whose parameter requires a validity checked. + Much of this functionality can be optionally disabled, but the client using the API need not be aware. + + F_supported_not\: + This is used to designate that the function or some part of the function is not supported. + This is primarily used by individuals altering the project but maintaing API compatibility. + Any function must therefore support returning F_suppoted_not. + + There are some projects that can be enabled/disabled such as f_capability and f_threads. + These may explicitly document returning F_supported_not. + + The F_suppoted_not may be used for other purposes as well. + @todo Consider replacing this with F_function_unsupported as a special case to allow for F_suppoted_not to be usable for normal purposes. + Using F_suppoted_not is currently ambiguous between the function being unsupported and some functionality provided by the function being unsupported. + +Common Return Types for f_status_t: + There are some f_status_t return types that are not required to be returned but are used quite often that they might seem required. + + F_none\: + This general designates that no error occurred. + This is a generic status code used all over the place. + + F_memory_not\: + This general designates that the operation ran out of memory. + This is a generic status code used all over the place. -- 1.8.3.1