[azcore] updating doc.go (Azure#15477)

* updating doc.go

* update changelog

* joels comments

* fix up package names and examples

* add section on logging

* add doc.go for sub-packages

Co-authored-by: Joel Hendrix <[email protected]>

sdk/azcore/CHANGELOG.md

@@ -3,12 +3,7 @@
 ## v0.20.0 (Unreleased)
 
 ### Features Added
-
-### Breaking Changes
-
-### Bug Fixes
-
-### Other Changes
+* Updating Documentation
 
 
 ## v0.19.0 (2021-08-25)

sdk/azcore/README.md

@@ -15,7 +15,7 @@ Typically, you will not need to explicitly install `azcore` as it will be instal
 To add the latest version to your `go.mod` file, execute the following command.
 
 ```bash
-go get -u github.com/Azure/azure-sdk-for-go/sdk/azcore
+go get github.com/Azure/azure-sdk-for-go/sdk/azcore
 ```
 
 General documentation and examples can be found on [pkg.go.dev](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azcore).

sdk/azcore/arm/doc.go

@@ -0,0 +1,9 @@
+//go:build go1.16
+// +build go1.16
+
+// Copyright 2017 Microsoft Corporation. All rights reserved.
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+// Package arm contains functionality specific to Azure Resource Manager clients.
+package arm

sdk/azcore/doc.go

@@ -11,8 +11,8 @@ Package azcore implements an HTTP request/response middleware pipeline.
 The middleware consists of three components.
 
    - One or more Policy instances.
-   - A Transport instance.
-   - A Pipeline instance that combines the Policy and Transport instances.
+   - A Transporter instance.
+   - A Pipeline instance that combines the Policy and Transporter instances.
 
 Implementing the Policy Interface
 
@@ -24,18 +24,25 @@ avoid race conditions.
 A Policy's Do method is called when an HTTP request wants to be sent over the network. The Do method can
 perform any operation(s) it desires. For example, it can log the outgoing request, mutate the URL, headers,
 and/or query parameters, inject a failure, etc.  Once the Policy has successfully completed its request
-work, it must call the Next() method on the *azcore.Request instance in order to pass the request to the
+work, it must call the Next() method on the *policy.Request instance in order to pass the request to the
 next Policy in the chain.
 
 When an HTTP response comes back, the Policy then gets a chance to process the response/error.  The Policy instance
 can log the response, retry the operation if it failed due to a transient error or timeout, unmarshal the response
-body, etc.  Once the Policy has successfully completed its response work, it must return the *azcore.Response
+body, etc.  Once the Policy has successfully completed its response work, it must return the *http.Response
 and error instances to its caller.
 
 Template for implementing a stateless Policy:
 
-   func NewMyStatelessPolicy() Policy {
-      return azcore.PolicyFunc(func(req *azcore.Request) (*azcore.Response, error) {
+   type policyFunc func(*policy.Request) (*http.Response, error)
+   // Do implements the Policy interface on policyFunc.
+
+   func (pf policyFunc) Do(req *policy.Request) (*http.Response, error) {
+	   return pf(req)
+   }
+
+   func NewMyStatelessPolicy() policy.Policy {
+      return policyFunc(func(req *policy.Request) (*http.Response, error) {
          // TODO: mutate/process Request here
 
          // forward Request to next Policy & get Response/error
@@ -55,13 +62,13 @@ Template for implementing a stateful Policy:
    }
 
    // TODO: add initialization args to NewMyStatefulPolicy()
-   func NewMyStatefulPolicy() Policy {
+   func NewMyStatefulPolicy() policy.Policy {
       return &MyStatefulPolicy{
          // TODO: initialize configuration/setting fields here
       }
    }
 
-   func (p *MyStatefulPolicy) Do(req *azcore.Request) (resp *azcore.Response, err error) {
+   func (p *MyStatefulPolicy) Do(req *policy.Request) (resp *http.Response, err error) {
          // TODO: mutate/process Request here
 
          // forward Request to next Policy & get Response/error
@@ -73,30 +80,30 @@ Template for implementing a stateful Policy:
          return resp, err
    }
 
-Implementing the Transport Interface
+Implementing the Transporter Interface
 
-The Transport interface is responsible for sending the HTTP request and returning the corresponding
-HTTP response or error.  The Transport is invoked by the last Policy in the chain.  The default Transport
+The Transporter interface is responsible for sending the HTTP request and returning the corresponding
+HTTP response or error.  The Transporter is invoked by the last Policy in the chain.  The default Transporter
 implementation uses a shared http.Client from the standard library.
 
-The same stateful/stateless rules for Policy implementations apply to Transport implementations.
+The same stateful/stateless rules for Policy implementations apply to Transporter implementations.
 
-Using Policy and Transport Instances Via a Pipeline
+Using Policy and Transporter Instances Via a Pipeline
 
-To use the Policy and Transport instances, an application passes them to the NewPipeline function.
+To use the Policy and Transporter instances, an application passes them to the runtime.NewPipeline function.
 
-   func NewPipeline(transport Transport, policies ...Policy) Pipeline
+   func NewPipeline(transport Transporter, policies ...Policy) Pipeline
 
 The specified Policy instances form a chain and are invoked in the order provided to NewPipeline
-followed by the Transport.
+followed by the Transporter.
 
-Once the Pipeline has been created, create a Request instance and pass it to Pipeline's Do method.
+Once the Pipeline has been created, create a runtime.Request instance and pass it to Pipeline's Do method.
 
    func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*Request, error)
 
-   func (p Pipeline) Do(req *Request) (*Response, error)
+   func (p Pipeline) Do(req *Request) (*http.Request, error)
 
-The Pipeline.Do method sends the specified Request through the chain of Policy and Transport
+The Pipeline.Do method sends the specified Request through the chain of Policy and Transporter
 instances.  The response/error is then sent through the same chain of Policy instances in reverse
 order.  For example, assuming there are Policy types PolicyA, PolicyB, and PolicyC along with
 TransportA.
@@ -105,17 +112,17 @@ TransportA.
 
 The flow of Request and Response looks like the following:
 
-   azcore.Request -> PolicyA -> PolicyB -> PolicyC -> TransportA -----+
+   policy.Request -> PolicyA -> PolicyB -> PolicyC -> TransportA -----+
                                                                       |
                                                                HTTP(s) endpoint
                                                                       |
-   caller <--------- PolicyA <- PolicyB <- PolicyC <- azcore.Response-+
+   caller <--------- PolicyA <- PolicyB <- PolicyC <- http.Response-+
 
 Creating a Request Instance
 
 The Request instance passed to Pipeline's Do method is a wrapper around an *http.Request.  It also
 contains some internal state and provides various convenience methods.  You create a Request instance
-by calling the NewRequest function:
+by calling the runtime.NewRequest function:
 
    func NewRequest(ctx context.Context, httpMethod string, endpoint string) (*Request, error)
 
@@ -158,11 +165,17 @@ This sends an explict "null" for Count, indicating that any current value for Co
 
 Processing the Response
 
-When the HTTP response is received, the underlying *http.Response is wrapped in a Response type.
-The Response type contains various convenience methods, like testing the HTTP response code and
-unmarshalling the response body in a particular format.
+When the HTTP response is received, the *http.Response is returned directly. Each Policy instance
+can inspect/mutate the *http.Response.
+
+Built-in Logging
+
+To enable logging, set environment variable AZURE_SDK_GO_LOGGING to "all" before executing your program.
+
+By default the logger writes to stderr.  This can be customized by calling log.SetListener, providing
+a callback that writes to the desired location.  Any custom logging implementation MUST provide its
+own synchronization to handle concurrent invocations.
 
-The Response is returned through all the Policy instances. Each Policy instance can inspect/mutate the
-embedded *http.Response.
+See the docs for the log package for further details.
 */
 package azcore

sdk/azcore/log/doc.go

@@ -0,0 +1,10 @@
+//go:build go1.16
+// +build go1.16
+
+// Copyright 2017 Microsoft Corporation. All rights reserved.
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+// Package log contains functionality for configuring logging behavior.
+// Default logging to stderr can be enabled by setting environment variable AZURE_SDK_GO_LOGGING to "all".
+package log

sdk/azcore/policy/doc.go

@@ -0,0 +1,10 @@
+//go:build go1.16
+// +build go1.16
+
+// Copyright 2017 Microsoft Corporation. All rights reserved.
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+// Package policy contains the definitions needed for configuring in-box pipeline policies
+// and creating custom policies.
+package policy

sdk/azcore/runtime/doc.go

@@ -0,0 +1,10 @@
+//go:build go1.16
+// +build go1.16
+
+// Copyright 2017 Microsoft Corporation. All rights reserved.
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+// Package runtime contains various facilities for creating requests and handling responses.
+// The content is intended for SDK authors.
+package runtime

sdk/azcore/runtime/policy_logging.go

@@ -24,7 +24,7 @@ type logPolicy struct {
 	options policy.LogOptions
 }
 
-// NewLogPolicy creates a RequestLogPolicy object configured using the specified options.
+// NewLogPolicy creates a request/response logging policy object configured using the specified options.
 // Pass nil to accept the default values; this is the same as passing a zero-value options.
 func NewLogPolicy(o *policy.LogOptions) policy.Policy {
 	if o == nil {

sdk/azcore/streaming/doc.go

@@ -0,0 +1,9 @@
+//go:build go1.16
+// +build go1.16
+
+// Copyright 2017 Microsoft Corporation. All rights reserved.
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+// Package streaming contains helpers for streaming IO operations and progress reporting.
+package streaming

sdk/azcore/to/doc.go

@@ -0,0 +1,9 @@
+//go:build go1.16
+// +build go1.16
+
+// Copyright 2017 Microsoft Corporation. All rights reserved.
+// Use of this source code is governed by an MIT
+// license that can be found in the LICENSE file.
+
+// Package to contains various type-conversion helper functions.
+package to