From 782d4b3284fe00f8d3a9183c2e9ec52f02436ca9 Mon Sep 17 00:00:00 2001 From: aimuz Date: Tue, 13 Sep 2022 12:48:29 +0800 Subject: [PATCH] new doc: the format after gofmt (#512) Signed-off-by: aimuz Signed-off-by: aimuz --- doc.go | 8 +++++--- interceptors/auth/doc.go | 4 +++- interceptors/logging/doc.go | 4 ++-- interceptors/ratelimit/doc.go | 4 +++- interceptors/recovery/doc.go | 4 +++- interceptors/retry/doc.go | 4 ++-- interceptors/skip/doc.go | 2 ++ interceptors/timeout/doc.go | 4 +++- interceptors/validator/doc.go | 5 +++-- providers/kit/doc.go | 4 ++-- providers/logr/doc.go | 5 ++--- providers/logrus/doc.go | 4 ++-- providers/zap/doc.go | 4 ++-- 13 files changed, 34 insertions(+), 22 deletions(-) diff --git a/doc.go b/doc.go index 52d26e696..c5ecd6b67 100644 --- a/doc.go +++ b/doc.go @@ -2,9 +2,11 @@ // Licensed under the Apache License 2.0. /* +Package middleware + `middleware` is a collection of gRPC middleware packages: interceptors, helpers and tools. -Middleware +# Middleware gRPC is a fantastic RPC middleware, which sees a lot of adoption in the Golang world. However, the upstream gRPC codebase is relatively bare bones. @@ -13,7 +15,7 @@ This package, and most of its child packages provides commonly needed middleware client-side interceptors for retires, server-side interceptors for input validation and auth, functions for chaining said interceptors, metadata convenience methods and more. -Chaining +# Chaining Simple way of turning a multiple interceptors into a single interceptor. Here's an example for server chaining: @@ -39,7 +41,7 @@ These interceptors will be executed from left to right: monitoring and then retr The retry interceptor will call every interceptor that follows it whenever when a retry happens. -Writing Your Own +# Writing Your Own Implementing your own interceptor is pretty trivial: there are interfaces for that. But the interesting bit exposing common data to handlers (and other middleware), similarly to HTTP Middleware design. diff --git a/interceptors/auth/doc.go b/interceptors/auth/doc.go index b3e62a343..27cadbc61 100644 --- a/interceptors/auth/doc.go +++ b/interceptors/auth/doc.go @@ -2,9 +2,11 @@ // Licensed under the Apache License 2.0. /* +Package auth is a middleware that authenticates incoming gRPC requests. + `auth` a generic server-side auth middleware for gRPC. -Server Side Auth Middleware +# Server Side Auth Middleware It allows for easy assertion of `:authorization` headers in gRPC calls, be it HTTP Basic auth, or OAuth2 Bearer tokens. diff --git a/interceptors/logging/doc.go b/interceptors/logging/doc.go index cc2e07124..d46e1f0a1 100644 --- a/interceptors/logging/doc.go +++ b/interceptors/logging/doc.go @@ -13,12 +13,12 @@ All logging middleware will emit a final log statement. It is based on the error the gRPC status code, an error (if any) and it emits at a level controlled via `WithLevels`. You can control this behavior using `WithDecider`. -This parent package +# This parent package This particular package is intended for use by other middleware, logging or otherwise. It contains interfaces that other logging middlewares *could* share. This allows code to be shared between different implementations. -Field names +# Field names All field names of loggers follow the OpenTracing semantics definitions, with `grpc.` prefix if needed: https://github.com/opentracing/specification/blob/master/semantic_conventions.md diff --git a/interceptors/ratelimit/doc.go b/interceptors/ratelimit/doc.go index e8004e5e0..83cd9e37b 100644 --- a/interceptors/ratelimit/doc.go +++ b/interceptors/ratelimit/doc.go @@ -2,9 +2,11 @@ // Licensed under the Apache License 2.0. /* +Package ratelimit is a middleware that limits the rate of requests. + `ratelimit` a generic server-side ratelimit middleware for gRPC. -Server Side Ratelimit Middleware +# Server Side Ratelimit Middleware It allows to do grpc rate limit by your own rate limiter (e.g. token bucket, leaky bucket, etc.) diff --git a/interceptors/recovery/doc.go b/interceptors/recovery/doc.go index 8adda9545..780212079 100644 --- a/interceptors/recovery/doc.go +++ b/interceptors/recovery/doc.go @@ -5,9 +5,11 @@ // See LICENSE for licensing terms. /* +Package recovery is a middleware that recovers from panics and logs the panic message. + `recovery` are interceptors that recover from gRPC handler panics. -Server Side Recovery Middleware +# Server Side Recovery Middleware By default a panic will be converted into a gRPC error with `code.Internal`. diff --git a/interceptors/retry/doc.go b/interceptors/retry/doc.go index 6f132c6b0..cad659022 100644 --- a/interceptors/retry/doc.go +++ b/interceptors/retry/doc.go @@ -4,7 +4,7 @@ /* Package retry provides client-side request retry logic for gRPC. -Client-Side Request Retry Interceptor +# Client-Side Request Retry Interceptor It allows for automatic retry, inside the generated gRPC code of requests based on the gRPC status of the reply. It supports unary (1:1), and server stream (1:n) requests. @@ -12,7 +12,7 @@ of the reply. It supports unary (1:1), and server stream (1:n) requests. By default the interceptors *are disabled*, preventing accidental use of retries. You can easily override the number of retries (setting them to more than 0) with a `grpc.ClientOption`, e.g.: - myclient.Ping(ctx, goodPing, grpc_retry.WithMax(5)) + myclient.Ping(ctx, goodPing, grpc_retry.WithMax(5)) Other default options are: retry on `ResourceExhausted` and `Unavailable` gRPC codes, use a 50ms linear backoff with 10% jitter. diff --git a/interceptors/skip/doc.go b/interceptors/skip/doc.go index 69ebbf21b..981f31a6a 100644 --- a/interceptors/skip/doc.go +++ b/interceptors/skip/doc.go @@ -2,6 +2,8 @@ // Licensed under the Apache License 2.0. /* +Package skip + `skip` allow users to skip interceptors in certain condition. Users can use grpc type, service name, method name and metadata to determine whether to skip the interceptor. diff --git a/interceptors/timeout/doc.go b/interceptors/timeout/doc.go index bf085d5cb..4e0886800 100644 --- a/interceptors/timeout/doc.go +++ b/interceptors/timeout/doc.go @@ -2,9 +2,11 @@ // Licensed under the Apache License 2.0. /* +Package timeout is a middleware that responds with a timeout error after the given duration. + `grpc_timeout` are interceptors that timeout for gRPC client calls. -Client Side Timeout Middleware +# Client Side Timeout Middleware Please see examples for simple examples of use. */ diff --git a/interceptors/validator/doc.go b/interceptors/validator/doc.go index bc692593a..816253ca9 100644 --- a/interceptors/validator/doc.go +++ b/interceptors/validator/doc.go @@ -2,9 +2,11 @@ // Licensed under the Apache License 2.0. /* +Package validator + `validator` is a generic request contents validator server-side middleware for gRPC. -Request Validator Middleware +# Request Validator Middleware Validating input is important, and hard. It also causes a lot of boilerplate code. This middleware checks for the existence of a `Validate` method on each of the messages of a gRPC request. This @@ -16,7 +18,6 @@ While it is generic, it was intended to be used with https://github.com/mwitkow/ a Go protocol buffers codegen plugin that creates the `Validate` methods (including nested messages) based on declarative options in the `.proto` files themselves. For example: - syntax = "proto3"; package validator.examples; import "github.com/mwitkow/go-proto-validators/validator.proto"; diff --git a/providers/kit/doc.go b/providers/kit/doc.go index 699e02a22..9ab11e212 100644 --- a/providers/kit/doc.go +++ b/providers/kit/doc.go @@ -2,7 +2,7 @@ // Licensed under the Apache License 2.0. /* -`kit` provides a small adapter required to use go-kit/log in logging gRPC middlewares. - Please see examples for examples of use. +Package kit provides a small adapter required to use go-kit/log in logging gRPC middlewares. +Please see examples for examples of use. */ package kit diff --git a/providers/logr/doc.go b/providers/logr/doc.go index ea9b43379..c322a48d0 100644 --- a/providers/logr/doc.go +++ b/providers/logr/doc.go @@ -2,8 +2,7 @@ // Licensed under the Apache License 2.0. /* -`logr` provides a small adapter required to use logr in logging gRPC middlewares. - - Please see examples for examples of use. +Package logr provides a small adapter required to use logr in logging gRPC middlewares. +Please see examples for examples of use. */ package logr diff --git a/providers/logrus/doc.go b/providers/logrus/doc.go index c11e176e8..10bb5d232 100644 --- a/providers/logrus/doc.go +++ b/providers/logrus/doc.go @@ -2,7 +2,7 @@ // Licensed under the Apache License 2.0. /* -`logrus` provides a small adapter required to use logrus in logging gRPC middlewares. - Please see examples for examples of use. +Package logrus provides a small adapter required to use logrus in logging gRPC middlewares. +Please see examples for examples of use. */ package logrus diff --git a/providers/zap/doc.go b/providers/zap/doc.go index 690356781..65f01793b 100644 --- a/providers/zap/doc.go +++ b/providers/zap/doc.go @@ -2,7 +2,7 @@ // Licensed under the Apache License 2.0. /* -`zap` provides a small adapter required to use zap in logging gRPC middlewares. - Please see examples for examples of use. +Package zap provides a small adapter required to use zap in logging gRPC middlewares. +Please see examples for examples of use. */ package zap