Improve documentation and code comments

Author: nexcode

README.md

@@ -5,33 +5,33 @@
 [![GoReportCard](https://goreportcard.com/badge/github.com/nexcode/rpcplatform)](https://goreportcard.com/report/github.com/nexcode/rpcplatform)
 [![CodeCov](https://codecov.io/gh/nexcode/rpcplatform/graph/badge.svg)](https://codecov.io/gh/nexcode/rpcplatform)
 
-An `easy-to-use` platform for creating microservices without complex infrastructure solutions.
-Only [etcd](https://etcd.io) required. Out of the box you get a service discovery, tracing between
-services and other useful things. [gRPC](https://grpc.io) is used for communication between services.
+An `easy-to-use` platform for creating microservices without complex infrastructure dependencies.
+Only [etcd](https://etcd.io) is required. Out of the box you get service discovery, tracing between
+services and other useful features. [gRPC](https://grpc.io) is used for communication between services.
 
-## etcd required
+## etcd is required
 
-If there is no etcd in your infrastructure, you can install it from a
-[docker container](https://etcd.io/docs/v3.6/op-guide/container/) for tests:
+If there is no etcd in your infrastructure, you can run it via
+[Docker](https://etcd.io/docs/v3.6/op-guide/container/) for testing:
 
 ```shell
 docker run -d --name etcd \
 	-p 2379:2379 -p 2380:2380 \
-	gcr.io/etcd-development/etcd:v3.6.5 /usr/local/bin/etcd \
-	--name etcd --initial-cluster etcd=http://127.0.0.1:2380 \
-	--initial-advertise-peer-urls http://127.0.0.1:2380 --listen-peer-urls http://0.0.0.0:2380 \
-	--advertise-client-urls http://127.0.0.1:2379 --listen-client-urls http://0.0.0.0:2379
+	-e ETCD_NAME=etcd -e ETCD_INITIAL_CLUSTER=etcd=http://127.0.0.1:2380 \
+	-e ETCD_INITIAL_ADVERTISE_PEER_URLS=http://127.0.0.1:2380 -e ETCD_LISTEN_PEER_URLS=http://0.0.0.0:2380 \
+	-e ETCD_ADVERTISE_CLIENT_URLS=http://127.0.0.1:2379 -e ETCD_LISTEN_CLIENT_URLS=http://0.0.0.0:2379 \
+	gcr.io/etcd-development/etcd:v3.6.5
 ```
 
-Of course, you can use docker in production or install etcd using your favorite package manager.
+Of course, you can use Docker in production or install etcd using your favorite package manager.
 Just remember that the example above is for testing purposes!
 
 ## How does it work?
 
-All you need to do is give your server a name. When it starts, it will automatically select a free port and run on it (unless you specify otherwise).
-All clients will connect to this server by its name. If there are multiple servers with the same name, load balancing will be performed between them.
+All you need to do is assign a name to your server. When it starts, it will automatically select a free port and listen on it (unless you specify otherwise).
+All clients will connect to this server by its name. If there are multiple servers with the same name, load balancing is distributed among them.
 
-> In the following code examples, error handling will be removed to improve readability. A pre-built [proto](examples/quickstart/proto) will also be used.
+> In the following code examples, error handling is omitted to improve readability. A pre-built [proto](examples/quickstart/proto) will also be used.
 
 First, let's create a new `rpcplatform` instance:
 
@@ -41,24 +41,24 @@ rpcp, err := rpcplatform.New("rpcplatform", etcdClient,
 		rpcplatform.ClientOptions.GRPCOptions(grpc.WithTransportCredentials(insecure.NewCredentials())),
 	),
 )
-````
+```
 
-Now let's create a new server named `myServerName`, give it the implementation of our `Sum` service and run it on the localhost (`sumServer` implementation will be omitted):
+Now let's create a new server named `myServerName`, register the implementation of our `Sum` service and run it on localhost (`sumServer` implementation is omitted):
 
 ```go
 server, err := rpcp.NewServer("myServerName", "localhost:")
 proto.RegisterSumServer(server.Server(), &sumServer{})
 err = server.Serve()
-````
+```
 
-And finally, we create a client that connects to our `myServerName` (`sumClient` usage will be omitted):
+And finally, we create a client that connects to our `myServerName` (`sumClient` usage is omitted):
 
 ```go
 client, err := rpcp.NewClient("myServerName")
 sumClient := proto.NewSumClient(client.Client())
-````
+```
 
-This is already enough for everything to work, we can add or remove copies of our server and add new clients — everything will work!
+This setup is fully functional: you can add or remove copies of your server and create new clients dynamically.
 But to see our **service graph** and get **telemetry for all gRPC methods**, we need to run containers with telemetry services and enable telemetry in `rpcplatform`.
 
 Let's run containers with Zipkin and Jaeger:
@@ -68,7 +68,7 @@ docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin
 docker run -d --name jaeger -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one
 ```
 
-Now let's create the necessary collectors and add `OpenTelemetry` option to the `rpcplatform` instance:
+Now let's create the necessary collectors and add the `OpenTelemetry` option to the `rpcplatform` instance:
 
 ```go
 otlpExporter, err := otlptracegrpc.New(context.Background(),
@@ -83,9 +83,9 @@ rpcp, err := rpcplatform.New("rpcplatform", etcdClient,
 	),
 	rpcplatform.PlatformOptions.OpenTelemetry("myServiceName", 1, otlpExporter, zipkinExporter),
 )
-````
+```
 
-The tracing system's web interface is available in a browser:
+The tracing dashboards are available at:
 
 | Zipkin (`http://localhost:9411`)             | Jaeger (`http://localhost:16686`)            |
 | :------------------------------------------: | :------------------------------------------: |
@@ -94,5 +94,5 @@ The tracing system's web interface is available in a browser:
 ## Usage examples (with source code)
 
 - [QuickStart](examples/quickstart): contains the simplest example without additional features
-- [OpenTelemetry](examples/opentelemetry): example with connecting distributed tracing systems
+- [OpenTelemetry](examples/opentelemetry): example integrating distributed tracing systems
 - [Attributes](examples/attributes): example using additional settings for client and server

attributes.go

@@ -20,10 +20,10 @@ import (
 	"github.com/nexcode/rpcplatform/internal/attributes"
 )
 
-// NewAttributes returns attributes with default values.
+// NewAttributes returns new Attributes with default values.
 func NewAttributes() *Attributes {
 	return attributes.New()
 }
 
-// Attributes provides server attribute values.
+// Attributes contains server attribute values.
 type Attributes = attributes.Attributes

client_client.go

@@ -20,7 +20,7 @@ import (
 	"google.golang.org/grpc"
 )
 
-// Client return the original gRPC ClientConn object.
+// Client returns the underlying gRPC ClientConn.
 func (c *Client) Client() *grpc.ClientConn {
 	return c.client
 }

client_id.go

@@ -16,7 +16,7 @@
 
 package rpcplatform
 
-// ID return the client identifier.
+// ID returns the client identifier.
 func (c *Client) ID() string {
 	return c.id
 }

examples/attributes/README.md

@@ -1,6 +1,6 @@
 ## Adding attributes
 
-This example is very similar to [QuickStart](../quickstart), but now we will use additional attributes for the server and will receive them on every update in the channel.
+This example is similar to the [QuickStart](../quickstart) example, but it uses additional server attributes that are sent with every channel update.
 
 ## Launching this demo
 
@@ -19,6 +19,6 @@ cd examples/opentelemetry/client
 go run .
 ```
 
-## Additional comments
+## Additional notes
 
-Currently there are two servers and one client running. If you launch another server, then one of the three servers will become a backup server, and the client will continue to interact with only two servers. If we want active servers to be selected using priority, we can use the `BalancerPriority` option for server attributes. Each server receives requests based on its weight, so by changing the value of `BalancerWeight` attribute we will distribute load the way we need.
+Currently, two servers and one client are running. If another server is launched, one becomes a backup server, and the client continues interacting with only two servers. To select active servers by priority, use the `BalancerPriority` server attribute. Each server receives requests based on its weight, so changing the `BalancerWeight` attribute value distributes load as needed.

examples/opentelemetry/README.md

@@ -1,16 +1,16 @@
-## Tracing systems preparation
+## Tracing system preparation
 
-In this example, we will connect two distributed tracing systems such as [Zipkin](https://zipkin.io) and [Jaeger](https://www.jaegertracing.io).
-You can run some of these systems or even use something else. List of supported [exporters](https://pkg.go.dev/go.opentelemetry.io/otel/exporters).
+In this example, we will connect two distributed tracing systems: [Zipkin](https://zipkin.io) and [Jaeger](https://www.jaegertracing.io).
+You can run these systems or use other alternatives. See the list of supported [exporters](https://pkg.go.dev/go.opentelemetry.io/otel/exporters).
 
-For the test, let's run two docker containers with tracing systems:
+For testing, let's run two Docker containers with the tracing systems:
 
 ```shell
 docker run -d --name zipkin -p 9411:9411 openzipkin/zipkin
 docker run -d --name jaeger -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one
 ```
 
-## Launching this demo
+## Launching the demo
 
 ```shell
 cd examples/opentelemetry/server
@@ -22,7 +22,7 @@ cd examples/opentelemetry/client
 go run .
 ```
 
-## Let's see the tracing reports
+## Viewing tracing reports
 
 - Open Zipkin UI in a browser: `http://localhost:9411`
 - Open Jaeger UI in a browser: `http://localhost:16686`

examples/quickstart/README.md

@@ -1,6 +1,6 @@
 ## Introduction to gRPC usage
 
-This example contains an already compiled [proto](proto) package.
+This example contains a pre-compiled [proto](proto) package.
 Detailed instructions for rebuilding (if needed) are [attached](proto/README.md).
 
 ## Launching this demo
@@ -20,11 +20,11 @@ cd examples/quickstart/client
 go run .
 ```
 
-Now two servers and one client are running!  
+You should now have two servers and one client running!
 
-## It works?
+## Does it work?
 
-Your console will have the corresponding logs:
+You will see the corresponding logs in your console:
 
 ```shell
 request: 4 + 9
@@ -41,5 +41,5 @@ request: 3 + 0
 1 + 3 = 4
 ```
 
-You can start new servers, stop running ones and add or remove clients...
-Everything will work!
+You can start additional servers, stop existing ones, and add or remove clients.
+The system will continue to function correctly!

internal/options/client.go

@@ -24,23 +24,16 @@ import (
 type Client struct{}
 
 // MaxActiveServers sets the maximum number of active servers the client will connect to.
-// If there are more servers than this value, no requests will be made to them.
+// Servers exceeding this limit will not receive requests.
 func (Client) MaxActiveServers(count int) func(*config.Client) {
 	return func(c *config.Client) {
 		c.MaxActiveServers = count
 	}
 }
 
-// GRPCOptions provide []grpc.DialOption to the client.
+// GRPCOptions adds gRPC dial options to the client.
 func (Client) GRPCOptions(options ...grpc.DialOption) func(*config.Client) {
 	return func(c *config.Client) {
 		c.GRPCOptions = append(c.GRPCOptions, options...)
 	}
 }
-
-// var Client ClientOption = client{}
-
-// type ClientOption interface {
-// 	MaxActiveServers(count int) func(*config.Client)
-// 	GRPCOptions(options ...grpc.DialOption) func(*config.Client)
-// }

internal/options/platform.go

@@ -23,21 +23,23 @@ import (
 
 type Platform struct{}
 
-// ClientOptions sets global settings for new clients that can be overwritten by local settings for each client.
+// ClientOptions sets default options for all new clients.
+// Local client options can override these global settings.
 func (Platform) ClientOptions(options ...func(*config.Client)) func(*config.Platform) {
 	return func(c *config.Platform) {
 		c.ClientOptions = append(c.ClientOptions, options...)
 	}
 }
 
-// ServerOptions sets global settings for new servers that can be overwritten by local settings for each server.
+// ServerOptions sets default options for all new servers.
+// Local server options can override these global settings.
 func (Platform) ServerOptions(options ...func(*config.Server)) func(*config.Platform) {
 	return func(c *config.Platform) {
 		c.ServerOptions = append(c.ServerOptions, options...)
 	}
 }
 
-// OpenTelemetry configures OpenTelemetry settings for clients and servers.
+// OpenTelemetry configures OpenTelemetry tracing for clients and servers.
 func (Platform) OpenTelemetry(serviceName string, sampleRate float64, exporters ...trace.SpanExporter) func(*config.Platform) {
 	return func(c *config.Platform) {
 		c.OpenTelemetry = &config.OpenTelemetry{

internal/options/server.go

@@ -24,21 +24,21 @@ import (
 
 type Server struct{}
 
-// PublicAddr is used when the server is not accessible to clients at the address it is located at.
+// PublicAddr sets the public address for the server when it is not accessible to clients at its listening address.
 func (Server) PublicAddr(publicAddr string) func(*config.Server) {
 	return func(c *config.Server) {
 		c.PublicAddr = publicAddr
 	}
 }
 
-// Attributes are server settings that are accessible via the API.
+// Attributes sets server attributes that are applied by the server and accessible via the Lookup method.
 func (Server) Attributes(attributes *attributes.Attributes) func(*config.Server) {
 	return func(c *config.Server) {
 		c.Attributes = attributes
 	}
 }
 
-// GRPCOptions provide []grpc.ServerOption to the server.
+// GRPCOptions adds gRPC server options to the server.
 func (Server) GRPCOptions(options ...grpc.ServerOption) func(*config.Server) {
 	return func(c *config.Server) {
 		c.GRPCOptions = append(c.GRPCOptions, options...)