doc updates and typos (#346)

* doc updates and typos

* Update materials.h

Reverting change from "materials providers" to "material provider"

* A bit more cleanup of doxygen comments

* Fixes from PR review

* Remove absolute paths from doxygen docs

* Clarification of base init function comments

Author: karlw00t

doxygen/doxygen.config.in

@@ -27,7 +27,7 @@ ABBREVIATE_BRIEF       = "The $name class" \
                          the
 ALWAYS_DETAILED_SEC    = NO
 INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = YES
+FULL_PATH_NAMES        = NO
 STRIP_FROM_PATH        = 
 STRIP_FROM_INC_PATH    = 
 SHORT_NAMES            = NO

include/aws/cryptosdk/edk.h

@@ -47,8 +47,8 @@ extern "C" {
 #endif
 
 /**
- * Deallocates all memory associated with an EDK. Setting all bytes of EDK to
- * zero upon creation will make this safe to call even if some buffers are unused.
+ * Deallocates all memory associated with an EDK. Setting all bytes of an EDK to
+ * zero when you declare it will make this safe to call even if some buffers are unused.
  */
 AWS_CRYPTOSDK_API
 void aws_cryptosdk_edk_clean_up(struct aws_cryptosdk_edk *edk);

include/aws/cryptosdk/header.h

@@ -19,8 +19,9 @@
 /**
  * @ingroup session
  * Known algorithm suite names.
- * These follow the format:
- *   [cipher algorithm]_IV[iv length]_AUTH[authtag length]_KD[KDF algorithm]_SIG[Signature algorithm, or NONE]
+ * For more information, see the <a
+ * href="https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/algorithms-reference.html">Algorithms
+ * Reference</a>.
  */
 enum aws_cryptosdk_alg_id {
     ALG_AES256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384 = 0x0378,

include/aws/cryptosdk/materials.h

@@ -325,7 +325,7 @@ struct aws_cryptosdk_cmm_vt {
 };
 
 /**
- * Initialize the base structure for a CMM. This should be called by the /implementation/ of a CMM, to set up the
+ * Initialize the base structure for a CMM. The implementation of a CMM needs to call this function to set up the
  * vtable and reference count. On return, the reference count is initialized to 1.
  */
 AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_cmm_base_init(
@@ -336,7 +336,7 @@ AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_cmm_base_init(
 
 /**
  * @ingroup cmm_kr_highlevel
- * Decrements the reference count on the CMM; if the new reference count is zero, the CMM is destroyed.
+ * Decrements the reference count on the CMM. If the new reference count is zero, the CMM is destroyed.
  */
 AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_cmm_release(struct aws_cryptosdk_cmm *cmm) {
     if (cmm && aws_cryptosdk_private_refcount_down(&cmm->refcount)) {
@@ -346,7 +346,7 @@ AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_cmm_release(struct aws_cryptosdk_
 
 /**
  * @ingroup cmm_kr_highlevel
- * Increments the reference count on the cmm.
+ * Increments the reference count on the CMM.
  */
 AWS_CRYPTOSDK_STATIC_INLINE struct aws_cryptosdk_cmm *aws_cryptosdk_cmm_retain(struct aws_cryptosdk_cmm *cmm) {
     aws_cryptosdk_private_refcount_up(&cmm->refcount);
@@ -440,8 +440,8 @@ struct aws_cryptosdk_keyring_vt {
 };
 
 /**
- * Initialize the base structure for a keyring. This should be called by the /implementation/ of a keyring, to set up
- * the vtable and reference count. On return, the reference count is initialized to 1.
+ * Initialize the base structure for a keyring. The implementation of a keyring needs to call this function
+ * to set up the vtable and reference count. On return, the reference count is initialized to 1.
  */
 AWS_CRYPTOSDK_STATIC_INLINE void aws_cryptosdk_keyring_base_init(
     struct aws_cryptosdk_keyring *keyring, const struct aws_cryptosdk_keyring_vt *vtable) {

include/aws/cryptosdk/session.h

@@ -100,16 +100,16 @@ int aws_cryptosdk_session_set_frame_size(struct aws_cryptosdk_session *session,
 
 /**
  * Sets the precise size of the message to encrypt. This function must be
- * called exactly once during an encrypt operation; it need not be called
+ * called exactly once during an encrypt operation. You do not need to call it
  * before beginning to pass data, but providing the message size up front may
  * improve efficiency.
  *
  * If the session has already processed more than message_size bytes, or if this
  * method is called more than once, the session will enter an error state.
  *
- * This method is how the end of data is determined; if this is not called, then
- * process will be unable to write out the end-of-message frames (and instead will
- * continue to request additional data).
+ * This method is how the end of data is determined. If this is not called,
+ * @ref aws_cryptosdk_session_process cannot write the end-of-message
+ * frames and instead will continue to expect additional data.
  *
  * Note that if the frame size is set to zero (i.e. this is a one-shot encrypt),
  * a message size must be set before any input data can be processed.
@@ -121,7 +121,7 @@ int aws_cryptosdk_session_set_message_size(struct aws_cryptosdk_session *session
  * Provides an upper bound on the message size. This hint is useful when the exact
  * message size is not known up-front, but the configured CMM still needs to make use
  * of message size information. For example, the caching CMM enforces an upper bound
- * on the number of bytes encrypted under a cached key; if this method is not called,
+ * on the number of bytes encrypted under a cached key. If this method is not called,
  * it must assume that you are processing an unbounded amount of data, and it will
  * therefore bypass the cache.
  *

include/aws/cryptosdk/version.h

@@ -26,11 +26,11 @@
  * the AWS Encryption SDKs in all languages, see the
  * <a href="https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/introduction.html">Developer Guide</a>.
  *
- * <b>This library is currently under public preview.</b>
+ * <b>This library is currently in public preview.</b>
  * Feel free to check out the code and give it a spin, but be aware that the APIs are still in flux.
  * We'd love to hear your feedback on the APIs before they're fully nailed down.
  *
- * Source code and installation instructions are avaiable in
+ * Source code and installation instructions are available in
  * <a href="https://github.com/awslabs/aws-encryption-sdk-c">the GitHub repository</a>.
  *
  *