Add comments to storage and fix some names (Azure#993)

sima-zhu · Aug 5, 2020 · faa1cc2 · faa1cc2
1 parent bc204d4
commit faa1cc2
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 17 deletions.
diff --git a/sdk/inc/azure/storage/az_storage_blobs.h b/sdk/inc/azure/storage/az_storage_blobs.h
@@ -19,10 +19,10 @@
 #include <azure/core/az_context.h>
 #include <azure/core/az_credentials.h>
 #include <azure/core/az_http.h>
-#include <azure/core/internal/az_http_internal.h>
 #include <azure/core/az_http_transport.h>
 #include <azure/core/az_result.h>
 #include <azure/core/az_span.h>
+#include <azure/core/internal/az_http_internal.h>
 
 #include <stdint.h>
 
@@ -33,16 +33,24 @@
  */
 static az_span const AZ_STORAGE_API_VERSION = AZ_SPAN_LITERAL_FROM_STR("2019-02-02");
 
+/**
+ * @brief Azure Storage Blobs blob client options
+ * @remark Allows customization of the blob client.
+ */
 typedef struct
 {
-  az_http_policy_retry_options retry;
+  az_http_policy_retry_options retry_options; /**< Optional values used to override the default retry policy options **/
   struct
   {
     _az_http_policy_apiversion_options api_version;
-    _az_http_policy_telemetry_options _telemetry_options;
+    _az_http_policy_telemetry_options telemetry_options;
   } _internal;
 } az_storage_blobs_blob_client_options;
 
+/**
+ * @brief Azure Storage Blobs Blob Client.
+ *
+ */
 typedef struct
 {
   struct
@@ -64,7 +72,7 @@ typedef struct
  * @param endpoint A url to a blob storage account.
  * @param credential The object used for authentication.
  *         #AZ_CREDENTIAL_ANONYMOUS should be used for SAS.
- * @param options  A reference to an #az_storage_blobs_blob_client_options structure which defines
+ * @param options A reference to an #az_storage_blobs_blob_client_options structure which defines
  * custom behavior of the client.
  *
  * @return An #az_result value indicating the result of the operation:
@@ -76,17 +84,20 @@ AZ_NODISCARD az_result az_storage_blobs_blob_client_init(
     void* credential,
     az_storage_blobs_blob_client_options* options);
 
+/**
+ * @brief Azure Storage Blobs Blob upload options.
+ * @remark Reserved for future use
+ */
 typedef struct
 {
   struct
   {
-    az_span option;
+    az_span unused;
   } _internal;
 } az_storage_blobs_blob_upload_options;
 
 /**
  * @brief Gets the default blob storage options.
- *
  * @details Call this to obtain an initialized #az_storage_blobs_blob_client_options structure that
  * can be modified and passed to #az_storage_blobs_blob_client_init().
  *
@@ -107,7 +118,7 @@ AZ_NODISCARD az_storage_blobs_blob_client_options az_storage_blobs_blob_client_o
 AZ_NODISCARD AZ_INLINE az_storage_blobs_blob_upload_options
 az_storage_blobs_blob_upload_options_default()
 {
-  return (az_storage_blobs_blob_upload_options){ ._internal = { .option = AZ_SPAN_NULL } };
+  return (az_storage_blobs_blob_upload_options){ ._internal = { .unused = AZ_SPAN_NULL } };
 }
 
 /**

diff --git a/sdk/src/azure/storage/az_storage_blobs_blob_client.c b/sdk/src/azure/storage/az_storage_blobs_blob_client.c
@@ -1,14 +1,14 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // SPDX-License-Identifier: MIT
 
-#include <azure/core/internal/az_config_internal.h>
-#include <azure/core/internal/az_credentials_internal.h>
 #include <azure/core/az_http.h>
-#include <azure/core/internal/az_http_internal.h>
 #include <azure/core/az_http_transport.h>
 #include <azure/core/az_json.h>
 #include <azure/core/az_precondition.h>
+#include <azure/core/internal/az_config_internal.h>
+#include <azure/core/internal/az_credentials_internal.h>
 #include <azure/core/internal/az_precondition_internal.h>
+#include <azure/core/internal/az_http_internal.h>
 #include <azure/core/internal/az_span_internal.h>
 #include <azure/storage/az_storage_blobs.h>
 
@@ -41,14 +41,14 @@ AZ_NODISCARD az_storage_blobs_blob_client_options az_storage_blobs_blob_client_o
           .version = AZ_STORAGE_API_VERSION,
         },
       },
-      ._telemetry_options = _az_http_policy_telemetry_options_default(),
+      .telemetry_options = _az_http_policy_telemetry_options_default(),
     },
-    .retry = _az_http_policy_retry_options_default(),
+    .retry_options = _az_http_policy_retry_options_default(),
   };
 
-  options.retry.max_retries = 5;
-  options.retry.retry_delay_msec = 1 * _az_TIME_MILLISECONDS_PER_SECOND;
-  options.retry.max_retry_delay_msec = 30 * _az_TIME_MILLISECONDS_PER_SECOND;
+  options.retry_options.max_retries = 5;
+  options.retry_options.retry_delay_msec = 1 * _az_TIME_MILLISECONDS_PER_SECOND;
+  options.retry_options.max_retry_delay_msec = 30 * _az_TIME_MILLISECONDS_PER_SECOND;
 
   return options;
 }
@@ -81,13 +81,13 @@ AZ_NODISCARD az_result az_storage_blobs_blob_client_init(
             {
               ._internal = {
                 .process = az_http_pipeline_policy_telemetry,
-                .options = &client->_internal.options._internal._telemetry_options,
+                .options = &client->_internal.options._internal.telemetry_options,
               },
             },
             {
               ._internal = {
                 .process = az_http_pipeline_policy_retry,
-                .options = &client->_internal.options.retry,
+                .options = &client->_internal.options.retry_options,
               },
             },
             {