Documentation for BlockBlobClient and Blob options (#235)

* Documentation for blob options

* Rename struct UploadBlobOptions -> UploadBlockBlobOptions

* documentation for BlockBlobClient

sdk/storage/inc/blobs/block_blob_client.hpp

@@ -13,52 +13,166 @@
 
 namespace Azure { namespace Storage { namespace Blobs {
 
+  /**
+   * @brief The BlockBlobClient allows you to manipulate Azure Storage block blobs.
+   *
+   * Block blobs let you upload large blobs efficiently. Block blobs are comprised of blocks, each
+   * of which is identified by a block ID. You create or modify a block blob by writing a set of
+   * blocks and committing them by their block IDs. Each block can be a different size.
+   *
+   * When you upload a block to a blob in your storage account, it is associated with the specified
+   * block blob, but it does not become part of the blob until you commit a list of blocks that
+   * includes the new block's ID. New blocks remain in an uncommitted state until they are
+   * specifically committed or discarded. Writing a block does not update the last modified time of
+   * an existing blob.
+   */
   class BlockBlobClient : public BlobClient {
   public:
-    // connection string
+    /**
+     * @brief Initialize a new instance of BlockBlobClient.
+     *
+     * @param connectionString A connection string includes the authentication information required
+     * for your application to access data in an Azure Storage account at runtime.
+     * @param containerName The name of the container containing this blob.
+     * @param blobName The name of this blob.
+     * @param options Optional client options that define the transport pipeline policies for
+     * authentication, retries, etc., that are applied to every request.
+     * @return A new BlockBlobClient instance.
+     */
     static BlockBlobClient CreateFromConnectionString(
         const std::string& connectionString,
         const std::string& containerName,
         const std::string& blobName,
         const BlockBlobClientOptions& options = BlockBlobClientOptions());
 
-    // shared key auth
+    /**
+     * @brief Initialize a new instance of BlockBlobClient.
+     *
+     * @param blobUri A uri
+     * referencing the blob that includes the name of the account, the name of the container, and
+     * the name of the blob.
+     * @param credential The shared key credential used to sign
+     * requests.
+     * @param options Optional client options that define the transport pipeline
+     * policies for authentication, retries, etc., that are applied to every request.
+     */
     explicit BlockBlobClient(
         const std::string& blobUri,
         std::shared_ptr<SharedKeyCredential> credential,
         const BlockBlobClientOptions& options = BlockBlobClientOptions());
 
-    // token auth
+    /**
+     * @brief Initialize a new instance of BlockBlobClient.
+     *
+     * @param blobUri A uri
+     * referencing the blob that includes the name of the account, the name of the container, and
+     * the name of the blob.
+     * @param credential The token credential used to sign requests.
+     * @param options Optional client options that define the transport pipeline policies for
+     * authentication, retries, etc., that are applied to every request.
+     */
     explicit BlockBlobClient(
         const std::string& blobUri,
         std::shared_ptr<TokenCredential> credential,
         const BlockBlobClientOptions& options = BlockBlobClientOptions());
 
-    // anonymous/SAS/customized pipeline auth
+    /**
+     * @brief Initialize a new instance of BlockBlobClient.
+     *
+     * @param blobUri A uri
+     * referencing the blob that includes the name of the account, the name of the container, and
+     * the name of the blob, and possibly also a SAS token.
+     * @param options Optional client
+     * options that define the transport pipeline policies for authentication, retries, etc., that
+     * are applied to every request.
+     */
     explicit BlockBlobClient(
         const std::string& blobUri,
         const BlockBlobClientOptions& options = BlockBlobClientOptions());
 
+    /**
+     * @brief Initializes a new instance of the BlockBlobClient class with an identical uri
+     * source but the specified snapshot timestamp.
+     *
+     * @param snapshot The snapshot
+     * identifier.
+     * @return A new BlockBlobClient instance.
+     * @remarks Pass empty string to remove the snapshot returning the base blob.
+     */
     BlockBlobClient WithSnapshot(const std::string& snapshot) const;
 
+    /**
+     * @brief Creates a new block blob, or updates the content of an existing block blob. Updating
+     * an existing block blob overwrites any existing metadata on the blob.
+     *
+     * @param content A BodyStream containing the content to upload.
+     * @param options Optional parameters to execute this function.
+     * @return A BlobContentInfo describing the state of the updated block blob.
+     */
     BlobContentInfo Upload(
         std::unique_ptr<Azure::Core::Http::BodyStream> content,
-        const UploadBlobOptions& options = UploadBlobOptions()) const;
+        const UploadBlockBlobOptions& options = UploadBlockBlobOptions()) const;
 
+    /**
+     * @brief Creates a new block as part of a block blob's staging area to be eventually
+     * committed via the CommitBlockList operation.
+     *
+     * @param blockId A valid Base64 string value that identifies the block. Prior to encoding, the
+     * string must be less than or equal to 64 bytes in size.
+     * @param content A BodyStream containing the content to upload.
+     * @param options Optional parameters to execute this function.
+     * @return A BlockInfo describing the state of the updated block.
+     */
     BlockInfo StageBlock(
         const std::string& blockId,
         std::unique_ptr<Azure::Core::Http::BodyStream> content,
         const StageBlockOptions& options = StageBlockOptions()) const;
 
+    /**
+     * @brief Creates a new block to be committed as part of a blob where the contents are read from
+     * the sourceUri.
+     *
+     * @param blockId A valid Base64 string value that identifies the block. Prior to encoding, the
+     * string must be less than or equal to 64 bytes in size.
+     * @param sourceUri Specifies the uri of the source
+     * blob. The value may be a uri of up to 2 KB in length that specifies a blob. The source blob
+     * must either be public or must be authenticated via a shared access signature. If the source
+     * blob is public, no authentication is required to perform the operation.
+     * @param options Optional parameters to execute this function.
+     * @return A BlockInfo describing the state of the updated block blob.
+     */
     BlockInfo StageBlockFromUri(
         const std::string& blockId,
         const std::string& sourceUri,
         const StageBlockFromUriOptions& options = StageBlockFromUriOptions()) const;
 
+    /**
+     * @brief Writes a blob by specifying the list of block IDs that make up the blob. In order to
+     * be written as part of a blob, a block must have been successfully written to the server in a
+     * prior StageBlock operation. You can call CommitBlockList to update a blob by uploading only
+     * those blocks that have changed, then committing the new and existing blocks together. You can
+     * do this by specifying whether to commit a block from the committed block list or from the
+     * uncommitted block list, or to commit the most recently uploaded version of the block,
+     * whichever list it may belong to.
+     *
+     * @param blockIds Base64 encoded block IDs to indicate that make up the blob.
+     * @param options Optional parameters to execute this function.
+     * @return A BlobContentInfo describing the state of the updated block blob.
+     */
     BlobContentInfo CommitBlockList(
         const std::vector<std::pair<BlockType, std::string>>& blockIds,
         const CommitBlockListOptions& options = CommitBlockListOptions()) const;
 
+    /**
+     * @brief Retrieves the list of blocks that have been uploaded as part of a block blob. There
+     * are two block lists maintained for a blob. The Committed Block list has blocks that have been
+     * successfully committed to a given blob with CommitBlockList. The Uncommitted Block list has
+     * blocks that have been uploaded for a blob using StageBlock, but that have not yet been
+     * committed.
+     *
+     * @param options Optional parameters to execute this function.
+     * @return A BlobBlockListInfo describing requested block list.
+     */
     BlobBlockListInfo GetBlockList(
         const GetBlockListOptions& options = GetBlockListOptions()) const;
 

sdk/storage/src/blobs/block_blob_client.cpp

@@ -59,7 +59,7 @@ namespace Azure { namespace Storage { namespace Blobs {
 
   BlobContentInfo BlockBlobClient::Upload(
       std::unique_ptr<Azure::Core::Http::BodyStream> content,
-      const UploadBlobOptions& options) const
+      const UploadBlockBlobOptions& options) const
   {
     BlobRestClient::BlockBlob::UploadOptions protocolLayerOptions;
     protocolLayerOptions.BodyStream = std::move(content);

sdk/storage/test/block_blob_client_test.cpp

@@ -22,7 +22,7 @@ namespace Azure { namespace Storage { namespace Test {
 
   std::shared_ptr<Azure::Storage::Blobs::BlockBlobClient> BlockBlobClientTest::m_blockBlobClient;
   std::string BlockBlobClientTest::m_blobName;
-  Azure::Storage::Blobs::UploadBlobOptions BlockBlobClientTest::m_blobUploadOptions;
+  Azure::Storage::Blobs::UploadBlockBlobOptions BlockBlobClientTest::m_blobUploadOptions;
   std::vector<uint8_t> BlockBlobClientTest::m_blobContent;
 
   void BlockBlobClientTest::SetUpTestSuite()

sdk/storage/test/block_blob_client_test.hpp

@@ -14,7 +14,7 @@ namespace Azure { namespace Storage { namespace Test {
 
     static std::shared_ptr<Azure::Storage::Blobs::BlockBlobClient> m_blockBlobClient;
     static std::string m_blobName;
-    static Azure::Storage::Blobs::UploadBlobOptions m_blobUploadOptions;
+    static Azure::Storage::Blobs::UploadBlockBlobOptions m_blobUploadOptions;
     static std::vector<uint8_t> m_blobContent;
   };