Improve doc comments for client constructors (#19293)

Azure · Oct 5, 2022 · eff7206 · eff7206
1 parent 12e98f5
commit eff7206
Show file tree

Hide file tree

Showing 10 changed files with 129 additions and 44 deletions.
diff --git a/sdk/storage/azblob/CHANGELOG.md b/sdk/storage/azblob/CHANGELOG.md
@@ -12,6 +12,8 @@
 
 ### Other Changes
 
+* Improved docs for client constructors.
+
 ## 0.5.0 (2022-09-29)
 
 ### Breaking Changes

diff --git a/sdk/storage/azblob/appendblob/client.go b/sdk/storage/azblob/appendblob/client.go
@@ -28,36 +28,49 @@ type ClientOptions struct {
 // Client represents a client to an Azure Storage append blob;
 type Client base.CompositeClient[generated.BlobClient, generated.AppendBlobClient]
 
-// NewClient creates an AppendBlobClient with the specified URL, Azure AD credential, and options.
-func NewClient(blobURL string, cred azcore.TokenCredential, o *ClientOptions) (*Client, error) {
+// NewClient creates an instance of Client with the specified values.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
+//   - cred - an Azure AD credential, typically obtained via the azidentity module
+//   - options - client options; pass nil to accept the default values
+func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
-	conOptions := shared.GetClientOptions(o)
+	conOptions := shared.GetClientOptions(options)
 	conOptions.PerRetryPolicies = append(conOptions.PerRetryPolicies, authPolicy)
 	pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
 
 	return (*Client)(base.NewAppendBlobClient(blobURL, pl, nil)), nil
 }
 
-// NewClientWithNoCredential creates an AppendBlobClient with the specified URL and options.
-func NewClientWithNoCredential(blobURL string, o *ClientOptions) (*Client, error) {
-	conOptions := shared.GetClientOptions(o)
+// NewClientWithNoCredential creates an instance of Client with the specified values.
+// This is used to anonymously access a blob or with a shared access signature (SAS) token.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt?<sas token>
+//   - options - client options; pass nil to accept the default values
+func NewClientWithNoCredential(blobURL string, options *ClientOptions) (*Client, error) {
+	conOptions := shared.GetClientOptions(options)
 	pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
 
 	return (*Client)(base.NewAppendBlobClient(blobURL, pl, nil)), nil
 }
 
-// NewClientWithSharedKeyCredential creates an AppendBlobClient with the specified URL, shared key, and options.
-func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCredential, o *ClientOptions) (*Client, error) {
+// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
+//   - cred - a SharedKeyCredential created with the matching blob's storage account and access key
+//   - options - client options; pass nil to accept the default values
+func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := exported.NewSharedKeyCredPolicy(cred)
-	conOptions := shared.GetClientOptions(o)
+	conOptions := shared.GetClientOptions(options)
 	conOptions.PerRetryPolicies = append(conOptions.PerRetryPolicies, authPolicy)
 	pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
 
 	return (*Client)(base.NewAppendBlobClient(blobURL, pl, cred)), nil
 }
 
-// NewClientFromConnectionString creates Client from a connection String
-func NewClientFromConnectionString(connectionString, containerName, blobName string, o *ClientOptions) (*Client, error) {
+// NewClientFromConnectionString creates an instance of Client with the specified values.
+//   - connectionString - a connection string for the desired storage account
+//   - containerName - the name of the container within the storage account
+//   - blobName - the name of the blob within the container
+//   - options - client options; pass nil to accept the default values
+func NewClientFromConnectionString(connectionString, containerName, blobName string, options *ClientOptions) (*Client, error) {
 	parsed, err := shared.ParseConnectionString(connectionString)
 	if err != nil {
 		return nil, err
@@ -69,10 +82,10 @@ func NewClientFromConnectionString(connectionString, containerName, blobName str
 		if err != nil {
 			return nil, err
 		}
-		return NewClientWithSharedKeyCredential(parsed.ServiceURL, credential, o)
+		return NewClientWithSharedKeyCredential(parsed.ServiceURL, credential, options)
 	}
 
-	return NewClientWithNoCredential(parsed.ServiceURL, o)
+	return NewClientWithNoCredential(parsed.ServiceURL, options)
 }
 
 // BlobClient returns the embedded blob client for this AppendBlob client.

diff --git a/sdk/storage/azblob/blob/client.go b/sdk/storage/azblob/blob/client.go
@@ -32,7 +32,10 @@ type ClientOptions struct {
 // Client represents a URL to an Azure Storage blob; the blob may be a block blob, append blob, or page blob.
 type Client base.Client[generated.BlobClient]
 
-// NewClient creates a Client object using the specified URL, Azure AD credential, and options.
+// NewClient creates an instance of Client with the specified values.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
+//   - cred - an Azure AD credential, typically obtained via the azidentity module
+//   - options - client options; pass nil to accept the default values
 func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
 	conOptions := shared.GetClientOptions(options)
@@ -42,15 +45,21 @@ func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptio
 	return (*Client)(base.NewBlobClient(blobURL, pl, nil)), nil
 }
 
-// NewClientWithNoCredential creates a Client object using the specified URL and options.
+// NewClientWithNoCredential creates an instance of Client with the specified values.
+// This is used to anonymously access a blob or with a shared access signature (SAS) token.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt?<sas token>
+//   - options - client options; pass nil to accept the default values
 func NewClientWithNoCredential(blobURL string, options *ClientOptions) (*Client, error) {
 	conOptions := shared.GetClientOptions(options)
 	pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
 
 	return (*Client)(base.NewBlobClient(blobURL, pl, nil)), nil
 }
 
-// NewClientWithSharedKeyCredential creates a Client object using the specified URL, shared key, and options.
+// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
+//   - cred - a SharedKeyCredential created with the matching blob's storage account and access key
+//   - options - client options; pass nil to accept the default values
 func NewClientWithSharedKeyCredential(blobURL string, cred *SharedKeyCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := exported.NewSharedKeyCredPolicy(cred)
 	conOptions := shared.GetClientOptions(options)
@@ -60,7 +69,11 @@ func NewClientWithSharedKeyCredential(blobURL string, cred *SharedKeyCredential,
 	return (*Client)(base.NewBlobClient(blobURL, pl, cred)), nil
 }
 
-// NewClientFromConnectionString creates Client from a connection String
+// NewClientFromConnectionString creates an instance of Client with the specified values.
+//   - connectionString - a connection string for the desired storage account
+//   - containerName - the name of the container within the storage account
+//   - blobName - the name of the blob within the container
+//   - options - client options; pass nil to accept the default values
 func NewClientFromConnectionString(connectionString, containerName, blobName string, options *ClientOptions) (*Client, error) {
 	parsed, err := shared.ParseConnectionString(connectionString)
 	if err != nil {

diff --git a/sdk/storage/azblob/blockblob/client.go b/sdk/storage/azblob/blockblob/client.go
@@ -35,7 +35,10 @@ type ClientOptions struct {
 // Client defines a set of operations applicable to block blobs.
 type Client base.CompositeClient[generated.BlobClient, generated.BlockBlobClient]
 
-// NewClient creates a Client object using the specified URL, Azure AD credential, and options.
+// NewClient creates an instance of Client with the specified values.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
+//   - cred - an Azure AD credential, typically obtained via the azidentity module
+//   - options - client options; pass nil to accept the default values
 func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
 	conOptions := shared.GetClientOptions(options)
@@ -45,15 +48,21 @@ func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptio
 	return (*Client)(base.NewBlockBlobClient(blobURL, pl, nil)), nil
 }
 
-// NewClientWithNoCredential creates a Client object using the specified URL and options.
+// NewClientWithNoCredential creates an instance of Client with the specified values.
+// This is used to anonymously access a blob or with a shared access signature (SAS) token.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt?<sas token>
+//   - options - client options; pass nil to accept the default values
 func NewClientWithNoCredential(blobURL string, options *ClientOptions) (*Client, error) {
 	conOptions := shared.GetClientOptions(options)
 	pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
 
 	return (*Client)(base.NewBlockBlobClient(blobURL, pl, nil)), nil
 }
 
-// NewClientWithSharedKeyCredential creates a Client object using the specified URL, shared key, and options.
+// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
+//   - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
+//   - cred - a SharedKeyCredential created with the matching blob's storage account and access key
+//   - options - client options; pass nil to accept the default values
 func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := exported.NewSharedKeyCredPolicy(cred)
 	conOptions := shared.GetClientOptions(options)
@@ -63,7 +72,11 @@ func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCreden
 	return (*Client)(base.NewBlockBlobClient(blobURL, pl, cred)), nil
 }
 
-// NewClientFromConnectionString creates Client from a connection String
+// NewClientFromConnectionString creates an instance of Client with the specified values.
+//   - connectionString - a connection string for the desired storage account
+//   - containerName - the name of the container within the storage account
+//   - blobName - the name of the blob within the container
+//   - options - client options; pass nil to accept the default values
 func NewClientFromConnectionString(connectionString, containerName, blobName string, options *ClientOptions) (*Client, error) {
 	parsed, err := shared.ParseConnectionString(connectionString)
 	if err != nil {

diff --git a/sdk/storage/azblob/client.go b/sdk/storage/azblob/client.go
@@ -27,7 +27,10 @@ type Client struct {
 	svc *service.Client
 }
 
-// NewClient creates a BlobClient object using the specified URL, Azure AD credential, and options.
+// NewClient creates an instance of Client with the specified values.
+//   - serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/
+//   - cred - an Azure AD credential, typically obtained via the azidentity module
+//   - options - client options; pass nil to accept the default values
 func NewClient(serviceURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
 	var clientOptions *service.ClientOptions
 	if options != nil {
@@ -43,7 +46,10 @@ func NewClient(serviceURL string, cred azcore.TokenCredential, options *ClientOp
 	}, nil
 }
 
-// NewClientWithNoCredential creates a BlobClient object using the specified URL and options.
+// NewClientWithNoCredential creates an instance of Client with the specified values.
+// This is used to anonymously access a storage account or with a shared access signature (SAS) token.
+//   - serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/?<sas token>
+//   - options - client options; pass nil to accept the default values
 func NewClientWithNoCredential(serviceURL string, options *ClientOptions) (*Client, error) {
 	var clientOptions *service.ClientOptions
 	if options != nil {
@@ -59,7 +65,10 @@ func NewClientWithNoCredential(serviceURL string, options *ClientOptions) (*Clie
 	}, nil
 }
 
-// NewClientWithSharedKeyCredential creates a BlobClient object using the specified URL, shared key, and options.
+// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
+//   - serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/
+//   - cred - a SharedKeyCredential created with the matching storage account and access key
+//   - options - client options; pass nil to accept the default values
 func NewClientWithSharedKeyCredential(serviceURL string, cred *SharedKeyCredential, options *ClientOptions) (*Client, error) {
 	svcClient, err := service.NewClientWithSharedKeyCredential(serviceURL, cred, (*service.ClientOptions)(options))
 	if err != nil {
@@ -71,7 +80,9 @@ func NewClientWithSharedKeyCredential(serviceURL string, cred *SharedKeyCredenti
 	}, nil
 }
 
-// NewClientFromConnectionString creates BlobClient from a connection String
+// NewClientFromConnectionString creates an instance of Client with the specified values.
+//   - connectionString - a connection string for the desired storage account
+//   - options - client options; pass nil to accept the default values
 func NewClientFromConnectionString(connectionString string, options *ClientOptions) (*Client, error) {
 	if options == nil {
 		options = &ClientOptions{}

diff --git a/sdk/storage/azblob/container/client.go b/sdk/storage/azblob/container/client.go
@@ -34,7 +34,10 @@ type ClientOptions struct {
 // Client represents a URL to the Azure Storage container allowing you to manipulate its blobs.
 type Client base.Client[generated.ContainerClient]
 
-// NewClient creates a Client object using the specified URL, Azure AD credential, and options.
+// NewClient creates an instance of Client with the specified values.
+//   - containerURL - the URL of the container e.g. https://<account>.blob.core.windows.net/container
+//   - cred - an Azure AD credential, typically obtained via the azidentity module
+//   - options - client options; pass nil to accept the default values
 func NewClient(containerURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
 	conOptions := shared.GetClientOptions(options)
@@ -44,15 +47,21 @@ func NewClient(containerURL string, cred azcore.TokenCredential, options *Client
 	return (*Client)(base.NewContainerClient(containerURL, pl, nil)), nil
 }
 
-// NewClientWithNoCredential creates a Client object using the specified URL and options.
+// NewClientWithNoCredential creates an instance of Client with the specified values.
+// This is used to anonymously access a container or with a shared access signature (SAS) token.
+//   - containerURL - the URL of the container e.g. https://<account>.blob.core.windows.net/container?<sas token>
+//   - options - client options; pass nil to accept the default values
 func NewClientWithNoCredential(containerURL string, options *ClientOptions) (*Client, error) {
 	conOptions := shared.GetClientOptions(options)
 	pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
 
 	return (*Client)(base.NewContainerClient(containerURL, pl, nil)), nil
 }
 
-// NewClientWithSharedKeyCredential creates a Client object using the specified URL, shared key, and options.
+// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
+//   - containerURL - the URL of the container e.g. https://<account>.blob.core.windows.net/container
+//   - cred - a SharedKeyCredential created with the matching container's storage account and access key
+//   - options - client options; pass nil to accept the default values
 func NewClientWithSharedKeyCredential(containerURL string, cred *SharedKeyCredential, options *ClientOptions) (*Client, error) {
 	authPolicy := exported.NewSharedKeyCredPolicy(cred)
 	conOptions := shared.GetClientOptions(options)
@@ -62,7 +71,10 @@ func NewClientWithSharedKeyCredential(containerURL string, cred *SharedKeyCreden
 	return (*Client)(base.NewContainerClient(containerURL, pl, cred)), nil
 }
 
-// NewClientFromConnectionString creates a Client object using connection string of an account
+// NewClientFromConnectionString creates an instance of Client with the specified values.
+//   - connectionString - a connection string for the desired storage account
+//   - containerName - the name of the container within the storage account
+//   - options - client options; pass nil to accept the default values
 func NewClientFromConnectionString(connectionString string, containerName string, options *ClientOptions) (*Client, error) {
 	parsed, err := shared.ParseConnectionString(connectionString)
 	if err != nil {

diff --git a/sdk/storage/azblob/lease/blob_client.go b/sdk/storage/azblob/lease/blob_client.go
@@ -33,6 +33,8 @@ type BlobClientOptions struct {
 }
 
 // NewBlobClient creates a blob lease client for the provided blob client.
+//   - client - an instance of a blob client
+//   - options - client options; pass nil to accept the default values
 func NewBlobClient[T appendblob.Client | blob.Client | blockblob.Client | pageblob.Client](client *T, options *BlobClientOptions) (*BlobClient, error) {
 	var leaseID *string
 	if options != nil {

diff --git a/sdk/storage/azblob/lease/container_client.go b/sdk/storage/azblob/lease/container_client.go
@@ -29,6 +29,8 @@ type ContainerClientOptions struct {
 }
 
 // NewContainerClient creates a container lease client for the provided container client.
+//   - client - an instance of a container client
+//   - options - client options; pass nil to accept the default values
 func NewContainerClient(client *container.Client, options *ContainerClientOptions) (*ContainerClient, error) {
 	var leaseID *string
 	if options != nil {