From 048c91ad108eb6ebc8631606ad32d7aeaad3be12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mi=C5=82osz=20Sm=C3=B3=C5=82ka?= Date: Wed, 24 Nov 2021 14:55:25 +0100 Subject: [PATCH] Fill missing godocs (#254) --- components/cqrs/command_processor.go | 4 ++++ components/cqrs/marshaler_protobuf.go | 6 ++++++ components/metrics/handler.go | 2 ++ log.go | 3 +++ message/message.go | 10 +++++++--- message/metadata.go | 2 ++ message/pubsub.go | 3 +++ message/router/middleware/recoverer.go | 1 + uuid.go | 3 +++ 9 files changed, 31 insertions(+), 3 deletions(-) diff --git a/components/cqrs/command_processor.go b/components/cqrs/command_processor.go index 540f768e8..b979148ee 100644 --- a/components/cqrs/command_processor.go +++ b/components/cqrs/command_processor.go @@ -48,6 +48,7 @@ type CommandProcessor struct { logger watermill.LoggerAdapter } +// NewCommandProcessor creates a new CommandProcessor. func NewCommandProcessor( handlers []CommandHandler, generateTopic func(commandName string) string, @@ -80,6 +81,7 @@ func NewCommandProcessor( }, nil } +// DuplicateCommandHandlerError occurs when a handler with the same name already exists. type DuplicateCommandHandlerError struct { CommandName string } @@ -88,6 +90,7 @@ func (d DuplicateCommandHandlerError) Error() string { return fmt.Sprintf("command handler for command %s already exists", d.CommandName) } +// AddHandlersToRouter adds the CommandProcessor's handlers to the given router. func (p CommandProcessor) AddHandlersToRouter(r *message.Router) error { handledCommands := map[string]struct{}{} @@ -130,6 +133,7 @@ func (p CommandProcessor) AddHandlersToRouter(r *message.Router) error { return nil } +// Handlers returns the CommandProcessor's handlers. func (p CommandProcessor) Handlers() []CommandHandler { return p.handlers } diff --git a/components/cqrs/marshaler_protobuf.go b/components/cqrs/marshaler_protobuf.go index 3dff6308a..474861094 100644 --- a/components/cqrs/marshaler_protobuf.go +++ b/components/cqrs/marshaler_protobuf.go @@ -10,11 +10,13 @@ import ( "github.com/pkg/errors" ) +// ProtobufMarshaler is the default Protocol Buffers marshaler. type ProtobufMarshaler struct { NewUUID func() string GenerateName func(v interface{}) string } +// NoProtoMessageError is returned when the given value does not implement proto.Message. type NoProtoMessageError struct { v interface{} } @@ -28,6 +30,7 @@ func (e NoProtoMessageError) Error() string { return "v is not proto.Message" } +// Marshal marshals the given protobuf's message into watermill's Message. func (m ProtobufMarshaler) Marshal(v interface{}) (*message.Message, error) { protoMsg, ok := v.(proto.Message) if !ok { @@ -57,10 +60,12 @@ func (m ProtobufMarshaler) newUUID() string { return watermill.NewUUID() } +// Unmarshal unmarshals given watermill's Message into protobuf's message. func (ProtobufMarshaler) Unmarshal(msg *message.Message, v interface{}) (err error) { return proto.Unmarshal(msg.Payload, v.(proto.Message)) } +// Name returns the command or event's name. func (m ProtobufMarshaler) Name(cmdOrEvent interface{}) string { if m.GenerateName != nil { return m.GenerateName(cmdOrEvent) @@ -69,6 +74,7 @@ func (m ProtobufMarshaler) Name(cmdOrEvent interface{}) string { return FullyQualifiedStructName(cmdOrEvent) } +// NameFromMessage returns the metadata name value for a given Message. func (m ProtobufMarshaler) NameFromMessage(msg *message.Message) string { return msg.Metadata.Get("name") } diff --git a/components/metrics/handler.go b/components/metrics/handler.go index d8dec4a0c..b9240426f 100644 --- a/components/metrics/handler.go +++ b/components/metrics/handler.go @@ -37,6 +37,7 @@ type HandlerPrometheusMetricsMiddleware struct { handlerExecutionTimeSeconds *prometheus.HistogramVec } +// Middleware returns the middleware ready to be used with watermill's Router. func (m HandlerPrometheusMetricsMiddleware) Middleware(h message.HandlerFunc) message.HandlerFunc { return func(msg *message.Message) (msgs []*message.Message, err error) { now := time.Now() @@ -58,6 +59,7 @@ func (m HandlerPrometheusMetricsMiddleware) Middleware(h message.HandlerFunc) me } } +// NewRouterMiddleware returns new middleware. func (b PrometheusMetricsBuilder) NewRouterMiddleware() HandlerPrometheusMetricsMiddleware { var err error m := HandlerPrometheusMetricsMiddleware{} diff --git a/log.go b/log.go index 92b5855cc..fc24c3a89 100644 --- a/log.go +++ b/log.go @@ -11,8 +11,10 @@ import ( "sync" ) +// LogFields is the logger's key-value list of fields. type LogFields map[string]interface{} +// Add adds new fields to the list of LogFields. func (l LogFields) Add(newFields LogFields) LogFields { resultFields := make(LogFields, len(l)+len(newFields)) @@ -26,6 +28,7 @@ func (l LogFields) Add(newFields LogFields) LogFields { return resultFields } +// Copy copies the LogFields. func (l LogFields) Copy() LogFields { cpy := make(LogFields, len(l)) for k, v := range l { diff --git a/message/message.go b/message/message.go index 4e943805a..0d8cd21ee 100644 --- a/message/message.go +++ b/message/message.go @@ -12,8 +12,11 @@ func init() { close(closedchan) } +// Payload is the Message's payload. type Payload []byte +// Message is the basic transfer unit. +// Messages are emitted by Publishers and received by Subscribers. type Message struct { // UUID is an unique identifier of message. // @@ -23,13 +26,13 @@ type Message struct { // Metadata contains the message metadata. // - // Can be used to store data which doesn't require unmarshaling entire payload. + // Can be used to store data which doesn't require unmarshaling the entire payload. // It is something similar to HTTP request's headers. // - // Metadata is marshaled and will be saved to PubSub. + // Metadata is marshaled and will be saved to the PubSub. Metadata Metadata - // Payload is message's payload. + // Payload is the message's payload. Payload Payload // ack is closed, when acknowledge is received. @@ -43,6 +46,7 @@ type Message struct { ctx context.Context } +// NewMessage creates a new Message with given uuid and payload. func NewMessage(uuid string, payload Payload) *Message { return &Message{ UUID: uuid, diff --git a/message/metadata.go b/message/metadata.go index 36409b634..c6e7e67a2 100644 --- a/message/metadata.go +++ b/message/metadata.go @@ -3,6 +3,7 @@ package message // Metadata is sent with every message to provide extra context without unmarshaling the message payload. type Metadata map[string]string +// Get returns the metadata value for the given key. If the key is not found, an empty string is returned. func (m Metadata) Get(key string) string { if v, ok := m[key]; ok { return v @@ -11,6 +12,7 @@ func (m Metadata) Get(key string) string { return "" } +// Set sets the metadata key to value. func (m Metadata) Set(key, value string) { m[key] = value } diff --git a/message/pubsub.go b/message/pubsub.go index d1badf19b..a1030d07a 100644 --- a/message/pubsub.go +++ b/message/pubsub.go @@ -4,6 +4,7 @@ import ( "context" ) +// Publisher is the emitting part of a Pub/Sub. type Publisher interface { // Publish publishes provided messages to given topic. // @@ -18,6 +19,7 @@ type Publisher interface { Close() error } +// Subscriber is the consuming part of the Pub/Sub. type Subscriber interface { // Subscribe returns output channel with messages from provided topic. // Channel is closed, when Close() was called on the subscriber. @@ -33,6 +35,7 @@ type Subscriber interface { Close() error } +// SubscribeInitializer is used to initialize subscribers. type SubscribeInitializer interface { // SubscribeInitialize can be called to initialize subscribe before consume. // When calling Subscribe before Publish, SubscribeInitialize should be not required. diff --git a/message/router/middleware/recoverer.go b/message/router/middleware/recoverer.go index 3de7ca03a..8551a5a37 100644 --- a/message/router/middleware/recoverer.go +++ b/message/router/middleware/recoverer.go @@ -9,6 +9,7 @@ import ( "github.com/pkg/errors" ) +// RecoveredPanicError holds the recovered panic's error along with the stacktrace. type RecoveredPanicError struct { V interface{} Stacktrace string diff --git a/uuid.go b/uuid.go index 372f62370..f3ad761a6 100644 --- a/uuid.go +++ b/uuid.go @@ -8,14 +8,17 @@ import ( "github.com/oklog/ulid" ) +// NewUUID returns a new UUID Version 4. func NewUUID() string { return uuid.New().String() } +// NewShortUUID returns a new short UUID. func NewShortUUID() string { return shortuuid.New() } +// NewULID returns a new ULID. func NewULID() string { return ulid.MustNew(ulid.Now(), rand.Reader).String() }