docs: Documentation clean up

README.md

@@ -52,7 +52,7 @@ CTEST_PARALLEL_LEVEL=$(nproc) ninja -C build test
 
 ### Amazonlinux2
 
-Install dependancies with `./codebuild/bin/install_al2_dependencies.sh` after cloning.
+Install dependencies with `./codebuild/bin/install_al2_dependencies.sh` after cloning.
 
 ```sh
 git clone https://github.com/${YOUR_GITHUB_ACCOUNT_NAME}/s2n-tls.git
@@ -62,12 +62,19 @@ cmake --build ./build -j $(nproc)
 CTEST_PARALLEL_LEVEL=$(nproc) make -C build test
 ```
 
-
 ## Have a Question?
 If you have any questions about Submitting PR's, Opening Issues, s2n-tls API usage, or something similar, we have a public chatroom available here to answer your questions: https://gitter.im/awslabs/s2n
 
 Otherwise, if you think you might have found a security impacting issue, please instead follow [our Security Notification Process.](#security-issue-notifications)
 
+## Documentation
+
+s2n-tls uses [Doxygen](https://doxygen.nl/index.html) to document its public API. The latest s2n-tls documentation can be found on [GitHub pages](https://aws.github.io/s2n-tls/doxygen/).
+
+Documentation for older versions or branches of s2n-tls can be generated locally. To generate the documentation, install doxygen and run `doxygen docs/doxygen/Doxyfile`. The doxygen documentation can now be found at `docs/doxygen/output/html/index.html`.
+
+Doxygen installation instructions are available at the [Doxygen](https://doxygen.nl/download.html) webpage.
+
 ## Using s2n-tls
 
 The s2n-tls I/O APIs are designed to be intuitive to developers familiar with the widely-used POSIX I/O APIs, and s2n-tls supports blocking, non-blocking, and full-duplex I/O. Additionally there are no locks or mutexes within s2n-tls. 
@@ -95,7 +102,7 @@ int bytes_written;
 bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked);
 ```
 
-For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [API Reference](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md).
+For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [usage guide](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md).
 
 ## s2n-tls features
 

api/s2n.h

@@ -136,16 +136,32 @@ extern int *s2n_errno_location(void);
  *
  * This enum is optimized for use in C switch statements. Each value in the enum represents
  * an error "category".
+ *
+ * s2n-tls organizes errors into different "types" to allow applications to handle error
+ * values without catching all possibilities. Applications using non-blocking I/O should check
+ * the error type to determine if the I/O operation failed because it would block or for some other
+ * error. To retrieve the type for a given error use `s2n_error_get_type()`. Applications should
+ * perform any error handling logic using these high level types.
+ *
+ * See the [Error Handling](https://github.com/aws/s2n-tls/blob/main/docs/USAGE-GUIDE.md#error-handling) section for how the errors should be interpreted. 
  */
 typedef enum {
-    S2N_ERR_T_OK=0,
-    S2N_ERR_T_IO,
-    S2N_ERR_T_CLOSED,
-    S2N_ERR_T_BLOCKED,
-    S2N_ERR_T_ALERT,
-    S2N_ERR_T_PROTO,
-    S2N_ERR_T_INTERNAL,
-    S2N_ERR_T_USAGE
+  /** No error */
+  S2N_ERR_T_OK=0,
+  /** Underlying I/O operation failed, check system errno */
+  S2N_ERR_T_IO, 
+  /** EOF */
+  S2N_ERR_T_CLOSED,
+  /** Underlying I/O operation would block */
+  S2N_ERR_T_BLOCKED,
+  /** Incoming Alert */
+  S2N_ERR_T_ALERT,
+  /** Failure in some part of the TLS protocol. Ex: CBC verification failure */
+  S2N_ERR_T_PROTO,
+  /** Error internal to s2n-tls. A precondition could have failed. */
+  S2N_ERR_T_INTERNAL,
+  /** User input error. Ex: Providing an invalid cipher preference version */
+  S2N_ERR_T_USAGE 
 } s2n_error_type;
 
 /**
@@ -176,6 +192,13 @@ struct s2n_connection;
  * prior to 1.1.x. This allows applications or languages that also init OpenSSL to interoperate
  * with S2N.
  *
+ * @warning This function must be called BEFORE s2n_init() to have any effect. It will return an error
+ * if s2n is already initialized.
+ *
+ * @note If you disable this and are using a version of OpenSSL/libcrypto < 1.1.x, you will
+ * be responsible for library init and cleanup (specifically `OPENSSL_add_all_algorithms()`
+ * or `OPENSSL_crypto_init()`, and EVP_* APIs will not be usable unless the library is initialized.
+ *
  * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
  */
 S2N_API
@@ -185,6 +208,12 @@ extern int s2n_crypto_disable_init(void);
  * Prevents S2N from installing an atexit handler, which allows safe shutdown of S2N from within a
  * re-entrant shared library
  *
+ * @warning This function must be called BEFORE s2n_init() to have any effect. It will return an error
+ * if s2n is already initialized.
+ *
+ * @note This will cause `s2n_cleanup` to do complete cleanup of s2n-tls when called from the main
+ * thread (the thread `s2n_init` was called from).
+ *
  * @returns S2N_SUCCESS on success. S2N_FAILURE on failure
  */
 S2N_API