update core document

core/const.go

@@ -1,24 +1,25 @@
 package core
 
+// ContextKey for context key, string alias
 type ContextKey string
 
 const (
 	// context
 	ContextHeaderXRequestID ContextKey = "X-Request-ID" // requestId key
 
-	DefaultServiceName = "xservice-default"
+	DefaultServiceName = "xservice-default" // default service name
 
 	// env key
-	EnvServiceName    = "XSERVICE_NAME"
-	EnvServiceVersion = "XSERVICE_VERSION"
-	EnvEtcd           = "XSERVICE_ETCD"
-	EnvEtcdUser       = "XSERVICE_ETCD_USER"
-	EnvEtcdPassword   = "XSERVICE_ETCD_PASSWORD"
+	EnvServiceName    = "XSERVICE_NAME"          // serviceName key
+	EnvServiceVersion = "XSERVICE_VERSION"       // serviceVersion key
+	EnvEtcd           = "XSERVICE_ETCD"          // etc endpoint key
+	EnvEtcdUser       = "XSERVICE_ETCD_USER"     // etcdUser key
+	EnvEtcdPassword   = "XSERVICE_ETCD_PASSWORD" // etcdPassword key
 
 	// config key
-	ConfigServiceAddr           = "http.address"
-	ConfigServiceAdvertisedAddr = "http.advertised_address"
+	ConfigServiceAddr           = "http.address"            // config http address key
+	ConfigServiceAdvertisedAddr = "http.advertised_address" // config http advertise address key
 
-	ServiceConfigKeyPrefix   = "xservice/config"
-	ServiceRegisterKeyPrefix = "xservice/register"
+	ServiceConfigKeyPrefix   = "xservice/config"   // service config key prefix
+	ServiceRegisterKeyPrefix = "xservice/register" // service register key prefix
 )

core/middleware/pprof.go

@@ -7,6 +7,7 @@ import (
 	"github.com/labstack/echo/v4"
 )
 
+// Pprof is pprof middleware
 func Pprof() echo.MiddlewareFunc {
 	return echo.WrapMiddleware(func(handler http.Handler) http.Handler {
 		return http.DefaultServeMux

core/middleware/prometheus.go

@@ -9,6 +9,7 @@ import (
 	"github.com/prometheus/client_golang/prometheus/promauto"
 )
 
+// Prometheus is prometheus middleware
 func Prometheus(namespace, subsystem string) echo.MiddlewareFunc {
 	requests := promauto.NewCounterVec(prometheus.CounterOpts{
 		Namespace: namespace,

core/middleware/trace.go

@@ -7,6 +7,7 @@ import (
 	"github.com/opentracing/opentracing-go"
 )
 
+// Trace is opentracing middleware
 func Trace(bodyDump bool, skipper middleware.Skipper) echo.MiddlewareFunc {
 	return jaegertracing.TraceWithConfig(jaegertracing.TraceConfig{
 		Tracer:     opentracing.GlobalTracer(),

core/xservice/client.go

@@ -14,7 +14,9 @@ import (
 	"github.com/xinpianchang/xservice/pkg/log"
 )
 
+// Client is the client for xservice
 type Client interface {
+	// GrpcClientConn returns a grpc client connection
 	GrpcClientConn(ctx context.Context, service string, desc *grpc.ServiceDesc, endpoint ...string) (*grpc.ClientConn, error)
 }
 
@@ -39,6 +41,7 @@ func newClient(opts *Options) Client {
 	return client
 }
 
+// GrpcClientConn returns a grpc client connection
 func (t *clientImpl) GrpcClientConn(ctx context.Context, service string, desc *grpc.ServiceDesc, endpoint ...string) (*grpc.ClientConn, error) {
 	if len(endpoint) > 0 {
 		return grpc.DialContext(ctx, endpoint[0], grpc.WithInsecure())

core/xservice/option.go

@@ -19,6 +19,7 @@ import (
 	"github.com/xinpianchang/xservice/pkg/netx"
 )
 
+// Options for xservice core option
 type Options struct {
 	Name               string
 	Version            string
@@ -30,50 +31,62 @@ type Options struct {
 	EchoTracingSkipper middleware.Skipper
 }
 
+// Option for option config
 type Option func(*Options)
 
+// Name set service name
 func Name(name string) Option {
 	return func(o *Options) {
 		o.Name = name
 	}
 }
 
+// Version set service version
 func Version(version string) Option {
 	return func(o *Options) {
 		o.Version = version
 	}
 }
 
+// Build set build version for service
 func Build(build string) Option {
 	return func(o *Options) {
 		o.Build = build
 	}
 }
 
+// Description set description for service
 func Description(description string) Option {
 	return func(o *Options) {
 		o.Description = description
 	}
 }
 
+// Config set custom viper instance for xservice configuration
+//
+// Note: default configuration enabled watch feature, if set custom viper,
+// watch feature should implements by you self
 func Config(config *viper.Viper) Option {
 	return func(o *Options) {
 		o.Config = config
 	}
 }
 
+// WithGrpcOptions add additional grpc server option
 func WithGrpcOptions(options ...grpc.ServerOption) Option {
 	return func(o *Options) {
 		o.GrpcOptions = options
 	}
 }
 
+// WithSentry set sentry option for enable sentry
 func WithSentry(options sentry.ClientOptions) Option {
 	return func(o *Options) {
 		o.SentryOptions = options
 	}
 }
 
+// WithEchoTracingSkipper set tracing skipper
 func WithEchoTracingSkipper(skipper middleware.Skipper) Option {
 	return func(o *Options) {
 		o.EchoTracingSkipper = skipper

core/xservice/server.go

@@ -40,9 +40,15 @@ import (
 	"github.com/xinpianchang/xservice/pkg/tracingx"
 )
 
+// Server is the interface for xservice server
 type Server interface {
+	// Echo returns the echo instance
 	Echo() *echo.Echo
+
+	// Serve start and listen server
 	Serve() error
+
+	// GrpcRegister registers a gRPC service
 	GrpcRegister(desc *grpc.ServiceDesc, impl interface{}, handler ...GrpcRegisterHandler)
 }
 
@@ -52,6 +58,7 @@ type grpcService struct {
 	Handler GrpcRegisterHandler
 }
 
+// GrpcRegisterHandler is the interface for gRPC service register handler
 type GrpcRegisterHandler func(ctx context.Context, mux *gwrt.ServeMux, conn *grpc.ClientConn) error
 
 type serverImpl struct {
@@ -79,6 +86,7 @@ func (t *serverImpl) Echo() *echo.Echo {
 	return t.echo
 }
 
+// Serve starts and listen server
 func (t *serverImpl) Serve() error {
 	address := t.getHttpAddress()
 
@@ -158,6 +166,7 @@ func (t *serverImpl) Serve() error {
 	return nil
 }
 
+// GrpcRegister registers a gRPC service
 func (t *serverImpl) GrpcRegister(desc *grpc.ServiceDesc, impl interface{}, hs ...GrpcRegisterHandler) {
 	var handler GrpcRegisterHandler
 	if len(hs) > 0 {

core/xservice/xservice.go

@@ -15,6 +15,7 @@ import (
 	"github.com/xinpianchang/xservice/pkg/tracingx"
 )
 
+// Service is a service interface, core api for xservice
 type Service interface {
 	Name() string
 	Options() *Options
@@ -29,6 +30,7 @@ type serviceImpl struct {
 	server  Server
 }
 
+// New create new xservice instance
 func New(options ...Option) Service {
 	opts := loadOptions(options...)
 
@@ -40,22 +42,27 @@ func New(options ...Option) Service {
 	return service
 }
 
+// Name get service name
 func (t *serviceImpl) Name() string {
 	return t.options.Name
 }
 
+// Options get service options
 func (t *serviceImpl) Options() *Options {
 	return t.options
 }
 
+// Client get service client
 func (t *serviceImpl) Client() Client {
 	return t.client
 }
 
+// Server get service server
 func (t *serviceImpl) Server() Server {
 	return t.server
 }
 
+// String get service formatted name
 func (t *serviceImpl) String() string {
 	return fmt.Sprint(t.Name(), "/", t.options.Version, " - ", t.options.Description)
 }