Skip to content

Commit eff7206

Browse files
jhendrixMSFTjhendrixMSFT
authored
Improve doc comments for client constructors (Azure#19293)
1 parent 12e98f5 commit eff7206

File tree

10 files changed

+129
-44
lines changed

10 files changed

+129
-44
lines changed

‎sdk/storage/azblob/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212

1313
### Other Changes
1414

15+
* Improved docs for client constructors.
16+
1517
## 0.5.0 (2022-09-29)
1618

1719
### Breaking Changes

‎sdk/storage/azblob/appendblob/client.go‎

Lines changed: 26 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -28,36 +28,49 @@ type ClientOptions struct {
2828
// Client represents a client to an Azure Storage append blob;
2929
type Client base.CompositeClient[generated.BlobClient, generated.AppendBlobClient]
3030

31-
// NewClient creates an AppendBlobClient with the specified URL, Azure AD credential, and options.
32-
func NewClient(blobURL string, cred azcore.TokenCredential, o *ClientOptions) (*Client, error) {
31+
// NewClient creates an instance of Client with the specified values.
32+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
33+
// - cred - an Azure AD credential, typically obtained via the azidentity module
34+
// - options - client options; pass nil to accept the default values
35+
func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
3336
authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
34-
conOptions := shared.GetClientOptions(o)
37+
conOptions := shared.GetClientOptions(options)
3538
conOptions.PerRetryPolicies = append(conOptions.PerRetryPolicies, authPolicy)
3639
pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
3740

3841
return (*Client)(base.NewAppendBlobClient(blobURL, pl, nil)), nil
3942
}
4043

41-
// NewClientWithNoCredential creates an AppendBlobClient with the specified URL and options.
42-
func NewClientWithNoCredential(blobURL string, o *ClientOptions) (*Client, error) {
43-
conOptions := shared.GetClientOptions(o)
44+
// NewClientWithNoCredential creates an instance of Client with the specified values.
45+
// This is used to anonymously access a blob or with a shared access signature (SAS) token.
46+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt?<sas token>
47+
// - options - client options; pass nil to accept the default values
48+
func NewClientWithNoCredential(blobURL string, options *ClientOptions) (*Client, error) {
49+
conOptions := shared.GetClientOptions(options)
4450
pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
4551

4652
return (*Client)(base.NewAppendBlobClient(blobURL, pl, nil)), nil
4753
}
4854

49-
// NewClientWithSharedKeyCredential creates an AppendBlobClient with the specified URL, shared key, and options.
50-
func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCredential, o *ClientOptions) (*Client, error) {
55+
// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
56+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
57+
// - cred - a SharedKeyCredential created with the matching blob's storage account and access key
58+
// - options - client options; pass nil to accept the default values
59+
func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCredential, options *ClientOptions) (*Client, error) {
5160
authPolicy := exported.NewSharedKeyCredPolicy(cred)
52-
conOptions := shared.GetClientOptions(o)
61+
conOptions := shared.GetClientOptions(options)
5362
conOptions.PerRetryPolicies = append(conOptions.PerRetryPolicies, authPolicy)
5463
pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
5564

5665
return (*Client)(base.NewAppendBlobClient(blobURL, pl, cred)), nil
5766
}
5867

59-
// NewClientFromConnectionString creates Client from a connection String
60-
func NewClientFromConnectionString(connectionString, containerName, blobName string, o *ClientOptions) (*Client, error) {
68+
// NewClientFromConnectionString creates an instance of Client with the specified values.
69+
// - connectionString - a connection string for the desired storage account
70+
// - containerName - the name of the container within the storage account
71+
// - blobName - the name of the blob within the container
72+
// - options - client options; pass nil to accept the default values
73+
func NewClientFromConnectionString(connectionString, containerName, blobName string, options *ClientOptions) (*Client, error) {
6174
parsed, err := shared.ParseConnectionString(connectionString)
6275
if err != nil {
6376
return nil, err
@@ -69,10 +82,10 @@ func NewClientFromConnectionString(connectionString, containerName, blobName str
6982
if err != nil {
7083
return nil, err
7184
}
72-
return NewClientWithSharedKeyCredential(parsed.ServiceURL, credential, o)
85+
return NewClientWithSharedKeyCredential(parsed.ServiceURL, credential, options)
7386
}
7487

75-
return NewClientWithNoCredential(parsed.ServiceURL, o)
88+
return NewClientWithNoCredential(parsed.ServiceURL, options)
7689
}
7790

7891
// BlobClient returns the embedded blob client for this AppendBlob client.

‎sdk/storage/azblob/blob/client.go‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,10 @@ type ClientOptions struct {
3232
// Client represents a URL to an Azure Storage blob; the blob may be a block blob, append blob, or page blob.
3333
type Client base.Client[generated.BlobClient]
3434

35-
// NewClient creates a Client object using the specified URL, Azure AD credential, and options.
35+
// NewClient creates an instance of Client with the specified values.
36+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
37+
// - cred - an Azure AD credential, typically obtained via the azidentity module
38+
// - options - client options; pass nil to accept the default values
3639
func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
3740
authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
3841
conOptions := shared.GetClientOptions(options)
@@ -42,15 +45,21 @@ func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptio
4245
return (*Client)(base.NewBlobClient(blobURL, pl, nil)), nil
4346
}
4447

45-
// NewClientWithNoCredential creates a Client object using the specified URL and options.
48+
// NewClientWithNoCredential creates an instance of Client with the specified values.
49+
// This is used to anonymously access a blob or with a shared access signature (SAS) token.
50+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt?<sas token>
51+
// - options - client options; pass nil to accept the default values
4652
func NewClientWithNoCredential(blobURL string, options *ClientOptions) (*Client, error) {
4753
conOptions := shared.GetClientOptions(options)
4854
pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
4955

5056
return (*Client)(base.NewBlobClient(blobURL, pl, nil)), nil
5157
}
5258

53-
// NewClientWithSharedKeyCredential creates a Client object using the specified URL, shared key, and options.
59+
// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
60+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
61+
// - cred - a SharedKeyCredential created with the matching blob's storage account and access key
62+
// - options - client options; pass nil to accept the default values
5463
func NewClientWithSharedKeyCredential(blobURL string, cred *SharedKeyCredential, options *ClientOptions) (*Client, error) {
5564
authPolicy := exported.NewSharedKeyCredPolicy(cred)
5665
conOptions := shared.GetClientOptions(options)
@@ -60,7 +69,11 @@ func NewClientWithSharedKeyCredential(blobURL string, cred *SharedKeyCredential,
6069
return (*Client)(base.NewBlobClient(blobURL, pl, cred)), nil
6170
}
6271

63-
// NewClientFromConnectionString creates Client from a connection String
72+
// NewClientFromConnectionString creates an instance of Client with the specified values.
73+
// - connectionString - a connection string for the desired storage account
74+
// - containerName - the name of the container within the storage account
75+
// - blobName - the name of the blob within the container
76+
// - options - client options; pass nil to accept the default values
6477
func NewClientFromConnectionString(connectionString, containerName, blobName string, options *ClientOptions) (*Client, error) {
6578
parsed, err := shared.ParseConnectionString(connectionString)
6679
if err != nil {

‎sdk/storage/azblob/blockblob/client.go‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,10 @@ type ClientOptions struct {
3535
// Client defines a set of operations applicable to block blobs.
3636
type Client base.CompositeClient[generated.BlobClient, generated.BlockBlobClient]
3737

38-
// NewClient creates a Client object using the specified URL, Azure AD credential, and options.
38+
// NewClient creates an instance of Client with the specified values.
39+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
40+
// - cred - an Azure AD credential, typically obtained via the azidentity module
41+
// - options - client options; pass nil to accept the default values
3942
func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
4043
authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
4144
conOptions := shared.GetClientOptions(options)
@@ -45,15 +48,21 @@ func NewClient(blobURL string, cred azcore.TokenCredential, options *ClientOptio
4548
return (*Client)(base.NewBlockBlobClient(blobURL, pl, nil)), nil
4649
}
4750

48-
// NewClientWithNoCredential creates a Client object using the specified URL and options.
51+
// NewClientWithNoCredential creates an instance of Client with the specified values.
52+
// This is used to anonymously access a blob or with a shared access signature (SAS) token.
53+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt?<sas token>
54+
// - options - client options; pass nil to accept the default values
4955
func NewClientWithNoCredential(blobURL string, options *ClientOptions) (*Client, error) {
5056
conOptions := shared.GetClientOptions(options)
5157
pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
5258

5359
return (*Client)(base.NewBlockBlobClient(blobURL, pl, nil)), nil
5460
}
5561

56-
// NewClientWithSharedKeyCredential creates a Client object using the specified URL, shared key, and options.
62+
// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
63+
// - blobURL - the URL of the blob e.g. https://<account>.blob.core.windows.net/container/blob.txt
64+
// - cred - a SharedKeyCredential created with the matching blob's storage account and access key
65+
// - options - client options; pass nil to accept the default values
5766
func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCredential, options *ClientOptions) (*Client, error) {
5867
authPolicy := exported.NewSharedKeyCredPolicy(cred)
5968
conOptions := shared.GetClientOptions(options)
@@ -63,7 +72,11 @@ func NewClientWithSharedKeyCredential(blobURL string, cred *blob.SharedKeyCreden
6372
return (*Client)(base.NewBlockBlobClient(blobURL, pl, cred)), nil
6473
}
6574

66-
// NewClientFromConnectionString creates Client from a connection String
75+
// NewClientFromConnectionString creates an instance of Client with the specified values.
76+
// - connectionString - a connection string for the desired storage account
77+
// - containerName - the name of the container within the storage account
78+
// - blobName - the name of the blob within the container
79+
// - options - client options; pass nil to accept the default values
6780
func NewClientFromConnectionString(connectionString, containerName, blobName string, options *ClientOptions) (*Client, error) {
6881
parsed, err := shared.ParseConnectionString(connectionString)
6982
if err != nil {

‎sdk/storage/azblob/client.go‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,10 @@ type Client struct {
2727
svc *service.Client
2828
}
2929

30-
// NewClient creates a BlobClient object using the specified URL, Azure AD credential, and options.
30+
// NewClient creates an instance of Client with the specified values.
31+
// - serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/
32+
// - cred - an Azure AD credential, typically obtained via the azidentity module
33+
// - options - client options; pass nil to accept the default values
3134
func NewClient(serviceURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
3235
var clientOptions *service.ClientOptions
3336
if options != nil {
@@ -43,7 +46,10 @@ func NewClient(serviceURL string, cred azcore.TokenCredential, options *ClientOp
4346
}, nil
4447
}
4548

46-
// NewClientWithNoCredential creates a BlobClient object using the specified URL and options.
49+
// NewClientWithNoCredential creates an instance of Client with the specified values.
50+
// This is used to anonymously access a storage account or with a shared access signature (SAS) token.
51+
// - serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/?<sas token>
52+
// - options - client options; pass nil to accept the default values
4753
func NewClientWithNoCredential(serviceURL string, options *ClientOptions) (*Client, error) {
4854
var clientOptions *service.ClientOptions
4955
if options != nil {
@@ -59,7 +65,10 @@ func NewClientWithNoCredential(serviceURL string, options *ClientOptions) (*Clie
5965
}, nil
6066
}
6167

62-
// NewClientWithSharedKeyCredential creates a BlobClient object using the specified URL, shared key, and options.
68+
// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
69+
// - serviceURL - the URL of the storage account e.g. https://<account>.blob.core.windows.net/
70+
// - cred - a SharedKeyCredential created with the matching storage account and access key
71+
// - options - client options; pass nil to accept the default values
6372
func NewClientWithSharedKeyCredential(serviceURL string, cred *SharedKeyCredential, options *ClientOptions) (*Client, error) {
6473
svcClient, err := service.NewClientWithSharedKeyCredential(serviceURL, cred, (*service.ClientOptions)(options))
6574
if err != nil {
@@ -71,7 +80,9 @@ func NewClientWithSharedKeyCredential(serviceURL string, cred *SharedKeyCredenti
7180
}, nil
7281
}
7382

74-
// NewClientFromConnectionString creates BlobClient from a connection String
83+
// NewClientFromConnectionString creates an instance of Client with the specified values.
84+
// - connectionString - a connection string for the desired storage account
85+
// - options - client options; pass nil to accept the default values
7586
func NewClientFromConnectionString(connectionString string, options *ClientOptions) (*Client, error) {
7687
if options == nil {
7788
options = &ClientOptions{}

‎sdk/storage/azblob/container/client.go‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,10 @@ type ClientOptions struct {
3434
// Client represents a URL to the Azure Storage container allowing you to manipulate its blobs.
3535
type Client base.Client[generated.ContainerClient]
3636

37-
// NewClient creates a Client object using the specified URL, Azure AD credential, and options.
37+
// NewClient creates an instance of Client with the specified values.
38+
// - containerURL - the URL of the container e.g. https://<account>.blob.core.windows.net/container
39+
// - cred - an Azure AD credential, typically obtained via the azidentity module
40+
// - options - client options; pass nil to accept the default values
3841
func NewClient(containerURL string, cred azcore.TokenCredential, options *ClientOptions) (*Client, error) {
3942
authPolicy := runtime.NewBearerTokenPolicy(cred, []string{shared.TokenScope}, nil)
4043
conOptions := shared.GetClientOptions(options)
@@ -44,15 +47,21 @@ func NewClient(containerURL string, cred azcore.TokenCredential, options *Client
4447
return (*Client)(base.NewContainerClient(containerURL, pl, nil)), nil
4548
}
4649

47-
// NewClientWithNoCredential creates a Client object using the specified URL and options.
50+
// NewClientWithNoCredential creates an instance of Client with the specified values.
51+
// This is used to anonymously access a container or with a shared access signature (SAS) token.
52+
// - containerURL - the URL of the container e.g. https://<account>.blob.core.windows.net/container?<sas token>
53+
// - options - client options; pass nil to accept the default values
4854
func NewClientWithNoCredential(containerURL string, options *ClientOptions) (*Client, error) {
4955
conOptions := shared.GetClientOptions(options)
5056
pl := runtime.NewPipeline(exported.ModuleName, exported.ModuleVersion, runtime.PipelineOptions{}, &conOptions.ClientOptions)
5157

5258
return (*Client)(base.NewContainerClient(containerURL, pl, nil)), nil
5359
}
5460

55-
// NewClientWithSharedKeyCredential creates a Client object using the specified URL, shared key, and options.
61+
// NewClientWithSharedKeyCredential creates an instance of Client with the specified values.
62+
// - containerURL - the URL of the container e.g. https://<account>.blob.core.windows.net/container
63+
// - cred - a SharedKeyCredential created with the matching container's storage account and access key
64+
// - options - client options; pass nil to accept the default values
5665
func NewClientWithSharedKeyCredential(containerURL string, cred *SharedKeyCredential, options *ClientOptions) (*Client, error) {
5766
authPolicy := exported.NewSharedKeyCredPolicy(cred)
5867
conOptions := shared.GetClientOptions(options)
@@ -62,7 +71,10 @@ func NewClientWithSharedKeyCredential(containerURL string, cred *SharedKeyCreden
6271
return (*Client)(base.NewContainerClient(containerURL, pl, cred)), nil
6372
}
6473

65-
// NewClientFromConnectionString creates a Client object using connection string of an account
74+
// NewClientFromConnectionString creates an instance of Client with the specified values.
75+
// - connectionString - a connection string for the desired storage account
76+
// - containerName - the name of the container within the storage account
77+
// - options - client options; pass nil to accept the default values
6678
func NewClientFromConnectionString(connectionString string, containerName string, options *ClientOptions) (*Client, error) {
6779
parsed, err := shared.ParseConnectionString(connectionString)
6880
if err != nil {

‎sdk/storage/azblob/lease/blob_client.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ type BlobClientOptions struct {
3333
}
3434

3535
// NewBlobClient creates a blob lease client for the provided blob client.
36+
// - client - an instance of a blob client
37+
// - options - client options; pass nil to accept the default values
3638
func NewBlobClient[T appendblob.Client | blob.Client | blockblob.Client | pageblob.Client](client *T, options *BlobClientOptions) (*BlobClient, error) {
3739
var leaseID *string
3840
if options != nil {

‎sdk/storage/azblob/lease/container_client.go‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ type ContainerClientOptions struct {
2929
}
3030

3131
// NewContainerClient creates a container lease client for the provided container client.
32+
// - client - an instance of a container client
33+
// - options - client options; pass nil to accept the default values
3234
func NewContainerClient(client *container.Client, options *ContainerClientOptions) (*ContainerClient, error) {
3335
var leaseID *string
3436
if options != nil {

0 commit comments

Comments
 (0)