cleans up all the readmes (#66)

* cleans up all the readmes

* fixed review comments

CONTRIBUTING.md

@@ -2,23 +2,17 @@
 
 Thank you for your interest in Dapr go SDK!
 
-This project welcomes contributions and suggestions. Most contributions require you to
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.
-agree to a Contributor License Agreement (CLA) declaring that you have the right to,
-and actually do, grant us the rights to use your contribution.
 
 For details, visit https://cla.microsoft.com.
 
-When you submit a pull request, a CLA-bot will automatically determine whether you need
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
-to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
-instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
 
-This project has adopted the Microsoft Open Source Code of Conduct.
+This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
-For more information see the Code of Conduct FAQ
-or contact opencode@microsoft.com with any additional questions or comments.
 
 Contributions come in many forms: submitting issues, writing code, participating in discussions and community calls.
 
-This document provides the guidelines for how to contribute to the Dapr project.
+This document provides the guidelines for how to contribute to the Dapr go SDK project.
 
 ## Issues
 
@@ -46,9 +40,9 @@ Before you file an issue, make sure you've checked the following:
     - Some changes to the Dapr go SDK may require changes to the API. In that case, the best place to discuss the potential feature is the main [Dapr repo](https://github.com/dapr/dapr).
     - Other examples could include bindings, state stores or entirely new components.
 
-## Contributing to Dapr
+## Contributing to Dapr go SDK
 
-This section describes the guidelines for contributing code / docs to Dapr.
+This section describes the guidelines for contributing code/docs to Dapr go SDK.
 
 ### Pull Requests
 
@@ -70,7 +64,7 @@ A good way to communicate before investing too much time is to create a "Work-in
 ### Use of Third-party code
 
 - All third-party code must be placed in the `vendor/` folder.
-- `vendor/` folder is managed by Go modules and stores the source code of third-party Go dependencies. - The `vendor/` folder should not be modified manually.
+- `vendor/` folder is managed by go modules which stores the source code of third-party go dependencies. - The `vendor/` folder should not be modified manually.
 - Third-party code must include licenses.
 
 A non-exclusive list of code that must be places in `vendor/`:

Readme.md

@@ -1,6 +1,6 @@
 # Dapr SDK for Go
 
-Client library to accelerate Dapr application development in go. This client supports all public [Dapr API](https://github.com/dapr/docs/tree/master/reference/api) and focuses on developer productivity. 
+Client library to help you build Dapr application in go. This client supports all public [Dapr APIs](https://github.com/dapr/docs/tree/master/reference/api) while focusing on idiomatic go experience and developer productivity. 
 
 [![Test](https://github.com/dapr/go-sdk/workflows/Test/badge.svg)](https://github.com/dapr/go-sdk/actions?query=workflow%3ATest) [![Release](https://github.com/dapr/go-sdk/workflows/Release/badge.svg)](https://github.com/dapr/go-sdk/actions?query=workflow%3ARelease) [![Go Report Card](https://goreportcard.com/badge/github.com/dapr/go-sdk)](https://goreportcard.com/report/github.com/dapr/go-sdk) ![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/dapr/go-sdk)
 
@@ -8,9 +8,9 @@ Client library to accelerate Dapr application development in go. This client sup
 
 > Assuming you already have [installed](https://golang.org/doc/install) go
 
-Dapr go client includes two packages: `client` (for invoking public Dapr API) and `service` (to create services in go that can be invoked by Dapr, this is sometimes refereed to as "callback"). 
+Dapr go client includes two packages: `client` (for invoking public Dapr API), and `service` (to create services that will be invoked by Dapr, this is sometimes refereed to as "callback"). 
 
-### Client 
+### Creating client 
 
 Import Dapr go `client` package:
 
@@ -37,7 +37,7 @@ func main() {
 }
 ```
 
-Assuming you have [Dapr CLI](https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md) installed locally, you can then launch your app locally like this:
+Assuming you have [Dapr CLI](https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md) installed, you can then launch your app locally like this:
 
 ```shell
 dapr run --app-id example-service \
@@ -46,17 +46,16 @@ dapr run --app-id example-service \
          go run main.go
 ```
 
-Check the [example folder](./example) for working Dapr go client examples.
+See the [example folder](./example) for more working Dapr client examples.
-
 
 #### Usage
 
-The Dapr go client supports following functionality: 
+The go client supports all the building blocks exposed by Dapr API. Let's review these one by one: 
 
 
 ##### State 
 
-For simple use-cases, Dapr client provides easy to use methods for `Save`, `Get`, and `Delete`: 
+For simple use-cases, Dapr client provides easy to use `Save`, `Get`, and `Delete` methods: 
 
 ```go
 ctx := context.Background()
@@ -81,7 +80,7 @@ if err := client.DeleteState(ctx, store, "key1"); err != nil {
 }
 ```
 
-For more granular control, the Dapr go client exposed `SetStateItem` type which can be use to gain more control over the state operations and allow for multiple items to be saved at once:
+For more granular control, the Dapr go client exposes `SetStateItem` type, which can be use to gain more control over the state operations and allow for multiple items to be saved at once:
 
 ```go     
 item1 := &dapr.SetStateItem{
@@ -123,7 +122,7 @@ keys := []string{"key1", "key2", "key3"}
 items, err := client.GetBulkItems(ctx, store, keys, 100)
 ```
 
-And the `ExecuteStateTransaction` method to transactionally execute multiple `upsert` or `delete` operations.
+And the `ExecuteStateTransaction` method to execute multiple `upsert` or `delete` operations transactionally.
 
 ```go
 ops := make([]*dapr.StateOperation, 0)
@@ -148,7 +147,7 @@ err := testClient.ExecuteStateTransaction(ctx, store, meta, ops)
 
 ##### PubSub 
 
-To publish data onto a topic the Dapr client provides a simple method:
+To publish data onto a topic, the Dapr client provides a simple method:
 
 ```go
 data := []byte(`{ "id": "a123", "value": "abcdefg", "valid": true }`)
@@ -238,7 +237,7 @@ func main() {
 
 ## Service (callback)
 
-In addition to this Dapr API client, Dapr go SDK also provides `service` package to bootstrap your Dapr callback services in either gRPC or HTTP. Instructions on how to use it are located [here](./service/Readme.md)
+In addition to the client capabilities that allow you to call into the Dapr API, the go SDK also provides `service` package to help you bootstrap Dapr callback services in either gRPC or HTTP. Instructions on how to use it are located [here](./service/Readme.md)
 
 ## Contributing to Dapr go client 
 

service/Readme.md

@@ -1,13 +1,13 @@
 # Dapr Service (Callback) SDK for Go
 
-In addition to this Dapr API client, Dapr go SDK also provides `service` package to bootstrap your Dapr callback services in either gRPC or HTTP:
+In addition to this Dapr API client, Dapr go SDK also provides `service` package to bootstrap your Dapr callback services. These services can be developed in either gRPC or HTTP:
 
 * [HTTP Service](./http/Readme.md)
 * [gRPC Service](./grpc/Readme.md)
 
 ## Templates 
 
-To accelerate your Dapr app development in go even further you can use one of the GitHub templates integrating these Dapr callback packages:
+To accelerate your Dapr app development in go even further, we've craated a few GitHub templates which build on the above Dapr callback packages:
 
 * [Dapr gRPC Service in Go](https://github.com/mchmarny/dapr-grpc-service-template) - Template project to jump start your Dapr event subscriber service with gRPC development
 * [Dapr HTTP Event Subscriber in Go](https://github.com/mchmarny/dapr-http-event-subscriber-template) - Template project to jump start your Dapr event subscriber service with HTTP development

service/grpc/Readme.md

@@ -6,57 +6,75 @@ Start by importing Dapr go `service/grpc` package:
 daprd "github.com/dapr/go-sdk/service/grpc"
 ```
 
-## Event Handling 
+## Creating and Starting Service 
 
-To handle events from specific topic, first create a Dapr service, add topic event handler, and start the service:
+To create a gRPC Dapr service, first, create a Dapr callback instance with a specific address:
 
 ```go
 s, err := daprd.NewService(":50001")
 if err != nil {
     log.Fatalf("failed to start the server: %v", err)
 }
+```
 
-if err := s.AddTopicEventHandler("messages", "topic1", eventHandler); err != nil {
+Or with address and an existing `net.Listener` in case you want to combine existing server listener:
-    log.Fatalf("error adding topic subscription: %v", err)
+
+```go
+list, err := net.Listen("tcp", "localhost:0")
+if err != nil {
+	log.Fatalf("gRPC listener creation failed: %s", err)
 }
+s, err := daprd.NewService(list)
+if err != nil {
+    log.Fatalf("failed to start the server: %v", err)
+}
+```
 
+Once you create a service instance, you can "attach" to that service any number of event, binding, and service invocation logic handlers as shown below. Onces the logic is defined, you are ready to start the service:
+
+```go
 if err := s.Start(); err != nil {
     log.Fatalf("server error: %v", err)
 }
+```
 
+
+## Event Handling 
+
+To handle events from specific topic you need to add at least one topic event handler before starting the service:
+
+```go
+if err := s.AddTopicEventHandler("messages", "topic1", eventHandler); err != nil {
+    log.Fatalf("error adding topic subscription: %v", err)
+}
+```
+
+The handler method itself can be any method with the expected signature:
+
+```go
 func eventHandler(ctx context.Context, e *daprd.TopicEvent) error {
 	log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
+	// do something with the event
 	return nil
 }
 ```
 
 ## Service Invocation Handler 
 
-To handle service invocations, create and start the Dapr service as in the above example. In this case though add the handler for service invocation: 
+To handle service invocations you will need to add at least one service invocation handler before starting the service: 
 
 ```go
-s, err := daprd.NewService(":50001")
-if err != nil {
-    log.Fatalf("failed to start the server: %v", err)
-}
-
 if err := s.AddServiceInvocationHandler("echo", echoHandler); err != nil {
     log.Fatalf("error adding invocation handler: %v", err)
 }
+```
 
-if err := s.Start(); err != nil {
+The handler method itself can be any method with the expected signature:
-    log.Fatalf("server error: %v", err)
-}
 
+```go
 func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.Content, err error) {
-	if in == nil {
+	log.Printf("echo - ContentType:%s, Verb:%s, QueryString:%s, %+v", in.ContentType, in.Verb, in.QueryString, string(in.Data))
-		err = errors.New("invocation parameter required")
+	// do something with the invocation here 
-		return
-	}
-	log.Printf(
-		"echo - ContentType:%s, Verb:%s, QueryString:%s, %+v",
-		in.ContentType, in.Verb, in.QueryString, string(in.Data),
-	)
 	out = &common.Content{
 		Data:        in.Data,
 		ContentType: in.ContentType,
@@ -68,31 +86,27 @@ func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.C
 
 ## Binding Invocation Handler 
 
-To handle binding invocations, create and start the Dapr service as in the above examples. In this case though add the handler for binding invocation: 
+To handle binding invocations you will need to add at least one binding invocation handler before starting the service: 
 
 ```go
-s, err := daprd.NewService(":50001")
-if err != nil {
-    log.Fatalf("failed to start the server: %v", err)
-}
-
 if err := s.AddBindingInvocationHandler("run", runHandler); err != nil {
     log.Fatalf("error adding binding handler: %v", err)
 }
+```
 
-if err := s.Start(); err != nil {
+The handler method itself can be any method with the expected signature:
-    log.Fatalf("server error: %v", err)
-}
 
+```go
 func runHandler(ctx context.Context, in *common.BindingEvent) (out []byte, err error) {
 	log.Printf("binding - Data:%v, Meta:%v", in.Data, in.Metadata)
+	// do something with the invocation here 
 	return nil, nil
 }
 ```
 
 ## Templates 
 
-To accelerate your Dapr app development in go even further you can use one of the GitHub templates integrating the gRPC Dapr callback package:
+To accelerate your gRPC Dapr app development in go even further you can use one of the GitHub templates integrating the gRPC Dapr callback package:
 
 * [Dapr gRPC Service in Go](https://github.com/mchmarny/dapr-grpc-service-template) - Template project to jump start your Dapr event subscriber service with gRPC development
 * [Dapr gRPC Event Subscriber in Go](https://github.com/mchmarny/dapr-grpc-event-subscriber-template) - Template project to jump start your Dapr event subscriber service with gRPC development

service/http/Readme.md

@@ -6,13 +6,35 @@ Start by importing Dapr go `service/http` package:
 daprd "github.com/dapr/go-sdk/service/http"
 ```
 
-## Event Handling 
+## Creating and Starting Service 
 
-To handle events from specific topic, first create a Dapr service, add topic event handler, and start the service:
+To create an HTTP Dapr service, first, create a Dapr callback instance with a specific address:
 
 ```go
 s := daprd.NewService(":8080")
+```
 
+Or with address and an existing `http.ServeMux` in case you want to combine existing server implementations:
+
+```go
+mux := http.NewServeMux()
+mux.HandleFunc("/", myOtherHandler)
+s := daprd.NewService(":8080", mux)
+```
+
+Once you create a service instance, you can "attach" to that service any number of event, binding, and service invocation logic handlers as shown below. Onces the logic is defined, you are ready to start the service:
+
+```go
+if err = s.Start(); err != nil && err != http.ErrServerClosed {
+	log.Fatalf("error: %v", err)
+}
+```
+
+## Event Handling 
+
+To handle events from specific topic you need to add at least one topic event handler before starting the service:
+
+```go
 sub := &common.Subscription{
 	PubsubName: "messages",
 	Topic: "topic1",
@@ -22,41 +44,34 @@ err := s.AddTopicEventHandler(sub, eventHandler)
 if err != nil {
 	log.Fatalf("error adding topic subscription: %v", err)
 }
+```
 
-if err = s.Start(); err != nil && err != http.ErrServerClosed {
+The handler method itself can be any method with the expected signature:
-	log.Fatalf("error listening: %v", err)
-}
 
+```go
 func eventHandler(ctx context.Context, e *common.TopicEvent) error {
 	log.Printf("event - PubsubName:%s, Topic:%s, ID:%s, Data: %v", e.PubsubName, e.Topic, e.ID, e.Data)
+	// do something with the event
 	return nil
 }
 ```
 
 ## Service Invocation Handler 
 
-To handle service invocations, create and start the Dapr service as in the above example. In this case though add the handler for service invocation: 
+To handle service invocations you will need to add at least one service invocation handler before starting the service: 
 
 ```go
-s := daprd.NewService(":8080")
-
 if err := s.AddServiceInvocationHandler("/echo", echoHandler); err != nil {
 	log.Fatalf("error adding invocation handler: %v", err)
 }
+```
 
-if err := s.Start(); err != nil {
+The handler method itself can be any method with the expected signature:
-    log.Fatalf("server error: %v", err)
-}
 
+```go
 func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.Content, err error) {
-	if in == nil {
+	log.Printf("echo - ContentType:%s, Verb:%s, QueryString:%s, %+v", in.ContentType, in.Verb, in.QueryString, string(in.Data))
-		err = errors.New("invocation parameter required")
+	// do something with the invocation here 
-		return
-	}
-	log.Printf(
-		"echo - ContentType:%s, Verb:%s, QueryString:%s, %+v",
-		in.ContentType, in.Verb, in.QueryString, string(in.Data),
-	)
 	out = &common.Content{
 		Data:        in.Data,
 		ContentType: in.ContentType,
@@ -68,24 +83,27 @@ func echoHandler(ctx context.Context, in *common.InvocationEvent) (out *common.C
 
 ## Binding Invocation Handler 
 
-To handle binding invocations, create and start the Dapr service as in the above examples. In this case though add the handler for binding invocation: 
+To handle binding invocations you will need to add at least one binding invocation handler before starting the service: 
 
 ```go
-s := daprd.NewService(":8080")
-
 if err := s.AddBindingInvocationHandler("/run", runHandler); err != nil {
 	log.Fatalf("error adding binding handler: %v", err)
 }
+```
 
+The handler method itself can be any method with the expected signature:
+
+```go
 func runHandler(ctx context.Context, in *common.BindingEvent) (out []byte, err error) {
 	log.Printf("binding - Data:%v, Meta:%v", in.Data, in.Metadata)
+	// do something with the invocation here 
 	return nil, nil
 }
 ```
 
 ## Templates 
 
-To accelerate your Dapr app development in go even further you can use one of the GitHub templates integrating the HTTP Dapr callback package:
+To accelerate your HTTP Dapr app development in go even further you can use one of the GitHub templates integrating the HTTP Dapr callback package:
 
 * [Dapr HTTP Event Subscriber in Go](https://github.com/mchmarny/dapr-http-event-subscriber-template) - Template project to jump start your Dapr event subscriber service with HTTP development
 * [Dapr HTTP cron Handler in Go](https://github.com/mchmarny/dapr-http-cron-handler-template) - Template project to jump start your Dapr service development for scheduled workloads