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

include/akerror.tmpl.h

@@ -176,8 +176,14 @@ void akerr_init_errno(void);
     switch ( 0 ) {				\
     case 0:					\
 
+#define VALID(__err_context, __stmt)                       \
+    __stmt;                                                \
+    if ( akerr_valid_error_address(__err_context) == 0 ) { \
+	FAIL(__err_context, AKERR_BEHAVIOR, "Received (akerr_Error *) from an invalid memory region. (Did the method finish without calling SUCCEED_RETURN?)"); \
+    }
+
 #define DETECT(__err_context, __stmt)					\
-    __stmt;								\
+    VALID(__err_context, __stmt);					\
     if ( __err_context != NULL ) {					\
 	__err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d: Detected error %d from array (refcount %d)\n", (char *)__FILE__, (char *)__func__, __LINE__, __err_context->arrayid, __err_context->refcount); \
 	if ( __err_context->status != 0 ) {				\
@@ -189,6 +195,13 @@ void akerr_init_errno(void);
 #define CATCH(__err_context, __stmt)			\
     DETECT(__err_context, __err_context = __stmt);
 
+#define PASS(__err_context, __stmt)               \
+    switch ( 0 ) {                                      \
+    case 0:                                             \
+	DETECT(__err_context, __err_context = __stmt);  \
+    }                                                   \
+    FINISH_LOGIC(__err_context, true);
+
 #define IGNORE(__stmt)							\
     __akerr_last_ignored = __stmt;					\
     if ( __akerr_last_ignored != NULL ) {				\
@@ -221,15 +234,18 @@ void akerr_init_errno(void);
     __err_context->stacktracebufptr = (char *)&__err_context->stacktracebuf; \
     __err_context->handled = true;
 
-#define FINISH(__err_context, __pass_up)				\
-    };									\
-    };									\
+#define FINISH_LOGIC(__err_context, __pass_up)                          \
     if ( __err_context != NULL ) {					\
 	if ( __err_context->handled == false && __pass_up == true ) {	\
 	    __err_context->stacktracebufptr += snprintf(__err_context->stacktracebufptr, AKERR_MAX_ERROR_STACKTRACE_BUF_LENGTH, "%s:%s:%d\n", (char *)__FILE__, (char *)__func__, __LINE__); \
 	    return __err_context;					\
 	}								\
     }									\
+
+#define FINISH(__err_context, __pass_up)				\
+    };									\
+    };									\
+    FINISH_LOGIC(__err_context, __pass_up)                              \
     RELEASE_ERROR(__err_context);
 
 #define FINISH_NORETURN(__err_context)					\
@@ -243,12 +259,4 @@ void akerr_init_errno(void);
     }									\
     RELEASE_ERROR(__err_context);
   
-#define CATCH_AND_RETURN(__err_context, __stmt) \
-    ATTEMPT {					\
-	CATCH(__err_context, __stmt);		\
-    } CLEANUP {					\
-      } PROCESS(__err_context) {		\
-	} FINISH(__err_context, true);		
-  
-
 #endif // _AKERR_H_