From: Kevin Day <thekevinday@gmail.com>
Date: Wed, 17 Mar 2021 03:54:43 +0000 (-0500)
Subject: Update: add documentation about return codes.
X-Git-Tag: 0.5.3~91
X-Git-Url: https://git.kevux.org/?a=commitdiff_plain;h=2fca68e18e46e35bcfb960aa1c33eb0ba6eb2f9d;p=fll

Update: add documentation about return codes.
---

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.