From 97718c293258445fdc0fc78d202fcc6b41ec2e4a Mon Sep 17 00:00:00 2001 From: haoqixu Date: Thu, 4 May 2023 10:32:38 +0800 Subject: [PATCH] chore(docs): add docs for public types and functions --- client/client.go | 3 ++- client/types/callbacks.go | 13 +++++++++++++ client/types/logger.go | 1 + client/types/packagessyncer.go | 1 + client/types/startsettings.go | 1 + 5 files changed, 18 insertions(+), 1 deletion(-) diff --git a/client/client.go b/client/client.go index 16d8d861..4c0ac375 100644 --- a/client/client.go +++ b/client/client.go @@ -7,6 +7,7 @@ import ( "github.com/open-telemetry/opamp-go/protobufs" ) +// OpAMPClient is an interface representing the client side of the OpAMP protocol. type OpAMPClient interface { // Start the client and begin attempts to connect to the Server. Once connection @@ -14,7 +15,7 @@ type OpAMPClient interface { // the connection is lost. All failed connection attempts will be reported via // OnConnectFailed callback. // - // AgentDescription in settings MUST be set. + // SetAgentDescription() MUST be called before Start(). // // Start may immediately return an error if the settings are incorrect (e.g. the // serverURL is not a valid URL). diff --git a/client/types/callbacks.go b/client/types/callbacks.go index 57799f9f..20f8fe32 100644 --- a/client/types/callbacks.go +++ b/client/types/callbacks.go @@ -6,6 +6,7 @@ import ( "github.com/open-telemetry/opamp-go/protobufs" ) +// MessageData represents a message received from the server and handled by Callbacks. type MessageData struct { // RemoteConfig is offered by the Server. The Agent must process it and call // OpAMPClient.SetRemoteConfigStatus to indicate success or failure. If the @@ -38,6 +39,7 @@ type MessageData struct { AgentIdentification *protobufs.AgentIdentification } +// Callbacks is an interface for the Client to handle messages from the Server. type Callbacks interface { // OnConnect is called when the connection is successfully established to the Server. // May be called after Start() is called and every time a connection is established to the Server. @@ -116,6 +118,8 @@ type Callbacks interface { OnCommand(command *protobufs.ServerToAgentCommand) error } +// CallbacksStruct is a struct that implements Callbacks interface and allows +// to override only the methods that are needed. If a method is not overridden then it is a no-op. type CallbacksStruct struct { OnConnectFunc func() OnConnectFailedFunc func(err error) @@ -139,36 +143,42 @@ type CallbacksStruct struct { var _ Callbacks = (*CallbacksStruct)(nil) +// OnConnect implements Callbacks.OnConnect. func (c CallbacksStruct) OnConnect() { if c.OnConnectFunc != nil { c.OnConnectFunc() } } +// OnConnectFailed implements Callbacks.OnConnectFailed. func (c CallbacksStruct) OnConnectFailed(err error) { if c.OnConnectFailedFunc != nil { c.OnConnectFailedFunc(err) } } +// OnError implements Callbacks.OnError. func (c CallbacksStruct) OnError(err *protobufs.ServerErrorResponse) { if c.OnErrorFunc != nil { c.OnErrorFunc(err) } } +// OnMessage implements Callbacks.OnMessage. func (c CallbacksStruct) OnMessage(ctx context.Context, msg *MessageData) { if c.OnMessageFunc != nil { c.OnMessageFunc(ctx, msg) } } +// SaveRemoteConfigStatus implements Callbacks.SaveRemoteConfigStatus. func (c CallbacksStruct) SaveRemoteConfigStatus(ctx context.Context, status *protobufs.RemoteConfigStatus) { if c.SaveRemoteConfigStatusFunc != nil { c.SaveRemoteConfigStatusFunc(ctx, status) } } +// GetEffectiveConfig implements Callbacks.GetEffectiveConfig. func (c CallbacksStruct) GetEffectiveConfig(ctx context.Context) (*protobufs.EffectiveConfig, error) { if c.GetEffectiveConfigFunc != nil { return c.GetEffectiveConfigFunc(ctx) @@ -176,6 +186,7 @@ func (c CallbacksStruct) GetEffectiveConfig(ctx context.Context) (*protobufs.Eff return nil, nil } +// OnOpampConnectionSettings implements Callbacks.OnOpampConnectionSettings. func (c CallbacksStruct) OnOpampConnectionSettings( ctx context.Context, settings *protobufs.OpAMPConnectionSettings, ) error { @@ -185,12 +196,14 @@ func (c CallbacksStruct) OnOpampConnectionSettings( return nil } +// OnOpampConnectionSettingsAccepted implements Callbacks.OnOpampConnectionSettingsAccepted. func (c CallbacksStruct) OnOpampConnectionSettingsAccepted(settings *protobufs.OpAMPConnectionSettings) { if c.OnOpampConnectionSettingsAcceptedFunc != nil { c.OnOpampConnectionSettingsAcceptedFunc(settings) } } +// OnCommand implements Callbacks.OnCommand. func (c CallbacksStruct) OnCommand(command *protobufs.ServerToAgentCommand) error { if c.OnCommandFunc != nil { return c.OnCommandFunc(command) diff --git a/client/types/logger.go b/client/types/logger.go index c258b936..0ba45ac0 100644 --- a/client/types/logger.go +++ b/client/types/logger.go @@ -1,5 +1,6 @@ package types +// Logger is the logging interface used by the OpAMP Client. type Logger interface { Debugf(format string, v ...interface{}) Errorf(format string, v ...interface{}) diff --git a/client/types/packagessyncer.go b/client/types/packagessyncer.go index f2857b44..a0aee495 100644 --- a/client/types/packagessyncer.go +++ b/client/types/packagessyncer.go @@ -24,6 +24,7 @@ type PackagesSyncer interface { Done() <-chan struct{} } +// PackageState represents the state of a package in the Agent's local storage. type PackageState struct { // Exists indicates that the package exists locally. The rest of the fields // must be ignored if this field is false. diff --git a/client/types/startsettings.go b/client/types/startsettings.go index 30e20033..b395afdb 100644 --- a/client/types/startsettings.go +++ b/client/types/startsettings.go @@ -7,6 +7,7 @@ import ( "github.com/open-telemetry/opamp-go/protobufs" ) +// StartSettings defines the parameters for starting the OpAMP Client. type StartSettings struct { // Connection parameters.