Update docs, replace the missing VALID() macro to safeguard against misbehaving functions, add PASS, remove CATCH_AND_RETURN

README.md

@@ -137,6 +137,14 @@ pkg_check_modules(akerror REQUIRED akerror)
 target_link_libraries(YOUR_TARGET PRIVATE akerror::akerror)
 ```
 
+Using this project as a submodule with cmake:
+
+```cmake
+add_subdirectory(deps/libakerror EXCLUDE_FROM_ALL)
+
+target_link_libraries(YOUR_PROJECT PRIVATE akerror::akerror)
+```
+
 
 ## (Optional) Configuring the logging function
 
@@ -222,6 +230,28 @@ ATTEMPT {
 
 When either of these two macros are used, the `ATTEMPT` block is immediately exited, and the `CLEANUP` block begins.
 
+# Passing errors
+
+Sometimes you can't actually do anything about the errors that come out of a given method, but you want that error to be propagated back up the call chain, and to be properly reported. If this is your goal, you can avoid using a `ATTEMPT ... FINISH` block, and simply use the `PASS` macro.
+
+```
+PREPARE_ERROR(e);
+PASS(e, some_method_that_may_fail());
+SUCCEED_RETURN(e);
+```
+
+This does the same thing as this, but with less code:
+
+```
+PREPARE_ERROR(e);
+ATTEMPT {
+    CATCH(e, some_method_that_may_fail());
+} CLEANUP {
+} PROCESS(e) {
+} FINISH(e, true);
+SUCCEED_RETURN(e);
+```
+
 # Handling errors
 
 Inside of the `PROCESS { ... }` block, you must handle any errors that occurred during the `ATTEMPT { ... }` block. You do this with `HANDLE`, `HANDLE_GROUP`, and `HANDLE_DEFAULT`.
@@ -310,20 +340,24 @@ FAIL_NONZERO_RETURN(errctx, strcmp("not", "equal"), AKERR_VALUE, "Strings are no
 
 # Uncaught errors
 
+## Misbehaving methods
+
+Any function which returns `akerr_ErrorContext *` and completes successfully MUST call `SUCCEED_RETURN(errctx)`. Failure to do this may result in an invalid `akerr_ErrorContext *` being returned, which will cause an `AKERR_BEHAVIOR` error to be triggered from your code. 
+
 ## Ensuring that all error codes are captured
 
-Any function which returns `akerr_ErrorContext *` should also be marked with `ERROR_NOIGNORE`.
+Any function which returns `akerr_ErrorContext *` should also be marked with `AKERROR_NOIGNORE`.
 
 ```c
-akerr_ErrorContext ERROR_NOIGNORE *f(...);
+akerr_ErrorContext AKERROR_NOIGNORE *f(...);
 ```
 
 This will cause a compile-time error if the return value of such a function is not used. "Used" here means assigned to a variable - it does not necessarily mean that the value is checked. However assuming that such functions are called inside of `ATTEMPT { ... }` blocks, it is safe to assume that such returns will be caught with `CATCH(...)`; therefore this error is a generally effective safeguard against careless coding where errors are not checked.
 
-Beware that `ERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`.
+Beware that `AKERROR_NOIGNORE` is not a failsafe - it implements the `warn_unused_result` mechanic. By design users may explicitly ignore an error code from a function marked with `warn_unused_result` by explicitly casting the return to `void`.
 
 ```c
-#define ERROR_NOIGNORE __attribute__((warn_unused_result))
+#define AKERROR_NOIGNORE __attribute__((warn_unused_result))
 ```
 
 ## Stack Traces