Add comments for admin api (#104)

* Add comments for admin api

Signed-off-by: xiaolong.ran <[email protected]>

* fix grammar

Signed-off-by: xiaolong.ran <[email protected]>

pkg/pulsar/broker_stats.go

@@ -17,18 +17,21 @@
 
 package pulsar
 
+// BrokerStats is admin interface for broker stats management
 type BrokerStats interface {
-	// Returns Monitoring metrics
+	// GetMetrics returns Monitoring metrics
 	GetMetrics() ([]Metrics, error)
 
-	// Requests JSON string server mbean dump
+	// GetMBeans requests JSON string server mbean dump
 	GetMBeans() ([]Metrics, error)
 
-	// Returns JSON string topics stats
+	// GetTopics returns JSON string topics stats
 	GetTopics() (string, error)
 
+	// GetLoadReport returns load report of broker
 	GetLoadReport() (*LocalBrokerData, error)
 
+	// GetAllocatorStats returns stats from broker
 	GetAllocatorStats(allocatorName string) (*AllocatorStats, error)
 }
 
@@ -37,6 +40,7 @@ type brokerStats struct {
 	basePath string
 }
 
+// BrokerStats is used to access the broker stats endpoints
 func (c *client) BrokerStats() BrokerStats {
 	return &brokerStats{
 		client:   c,

pkg/pulsar/brokers.go

@@ -23,34 +23,35 @@ import (
 	"strings"
 )
 
+// Brokers is admin interface for brokers management
 type Brokers interface {
-	// Get the list of active brokers in the cluster.
+	// GetActiveBrokers returns the list of active brokers in the cluster.
 	GetActiveBrokers(cluster string) ([]string, error)
 
-	// Get list of updatable configuration name
+	// GetDynamicConfigurationNames returns list of updatable configuration name
 	GetDynamicConfigurationNames() ([]string, error)
 
-	// Get the map of owned namespaces and their status from a single broker in the cluster
+	// GetOwnedNamespaces returns the map of owned namespaces and their status from a single broker in the cluster
 	GetOwnedNamespaces(cluster, brokerURL string) (map[string]NamespaceOwnershipStatus, error)
 
-	// It updates dynamic configuration value in to Zk that triggers watch on
+	// UpdateDynamicConfiguration updates dynamic configuration value in to Zk that triggers watch on
 	// brokers and all brokers can update {@link ServiceConfiguration} value locally
 	UpdateDynamicConfiguration(configName, configValue string) error
 
-	// It deletes dynamic configuration value in to Zk. It will not impact current value
+	// DeleteDynamicConfiguration deletes dynamic configuration value in to Zk. It will not impact current value
 	// in broker but next time when broker restarts, it applies value from configuration file only.
 	DeleteDynamicConfiguration(configName string) error
 
-	// Get values of runtime configuration
+	// GetRuntimeConfigurations returns values of runtime configuration
 	GetRuntimeConfigurations() (map[string]string, error)
 
-	// Get the internal configuration data
+	// GetInternalConfigurationData returns the internal configuration data
 	GetInternalConfigurationData() (*InternalConfigurationData, error)
 
-	// Get values of all overridden dynamic-configs
+	// GetAllDynamicConfigurations returns values of all overridden dynamic-configs
 	GetAllDynamicConfigurations() (map[string]string, error)
 
-	// Run a health check on the broker
+	// HealthCheck run a health check on the broker
 	HealthCheck() error
 }
 
@@ -59,6 +60,7 @@ type broker struct {
 	basePath string
 }
 
+// Brokers is used to access the brokers endpoints
 func (c *client) Brokers() Brokers {
 	return &broker{
 		client:   c,

pkg/pulsar/cluster.go

@@ -17,20 +17,42 @@
 
 package pulsar
 
-// Clusters  is used to access the cluster endpoints.
-
+// Clusters is admin interface for clusters management
 type Clusters interface {
+	// List returns the list of clusters
 	List() ([]string, error)
+
+	// Get the configuration data for the specified cluster
 	Get(string) (ClusterData, error)
+
+	// Create a new cluster
 	Create(ClusterData) error
+
+	// Delete an existing cluster
 	Delete(string) error
+
+	// Update the configuration for a cluster
 	Update(ClusterData) error
+
+	// UpdatePeerClusters updates peer cluster names.
 	UpdatePeerClusters(string, []string) error
+
+	// GetPeerClusters returns peer-cluster names
 	GetPeerClusters(string) ([]string, error)
+
+	// CreateFailureDomain creates a domain into cluster
 	CreateFailureDomain(FailureDomainData) error
+
+	// GetFailureDomain returns the domain registered into a cluster
 	GetFailureDomain(clusterName, domainName string) (FailureDomainData, error)
+
+	// ListFailureDomains returns all registered domains in cluster
 	ListFailureDomains(string) (FailureDomainMap, error)
+
+	// DeleteFailureDomain deletes a domain in cluster
 	DeleteFailureDomain(FailureDomainData) error
+
+	// UpdateFailureDomain updates a domain into cluster
 	UpdateFailureDomain(FailureDomainData) error
 }
 
@@ -39,6 +61,7 @@ type clusters struct {
 	basePath string
 }
 
+// Clusters is used to access the cluster endpoints.
 func (c *client) Clusters() Clusters {
 	return &clusters{
 		client:   c,

pkg/pulsar/functions.go

@@ -29,11 +29,13 @@ import (
 	"strings"
 )
 
+// Functions is admin interface for functions management
 type Functions interface {
-	// Create a new function.
+	// CreateFunc create a new function.
 	CreateFunc(data *FunctionConfig, fileName string) error
 
-	// Create a new function by providing url from which fun-pkg can be downloaded. supported url: http/file
+	// CreateFuncWithURL create a new function by providing url from which fun-pkg can be downloaded.
+	// supported url: http/file
 	// eg:
 	//  File: file:/dir/fileName.jar
 	//  Http: http://www.repo.com/fileName.jar
@@ -44,61 +46,61 @@ type Functions interface {
 	//      url from which pkg can be downloaded
 	CreateFuncWithURL(data *FunctionConfig, pkgURL string) error
 
-	// Stop all function instances
+	// StopFunction stop all function instances
 	StopFunction(tenant, namespace, name string) error
 
-	// Stop function instance
+	// StopFunctionWithID stop function instance
 	StopFunctionWithID(tenant, namespace, name string, instanceID int) error
 
-	// Delete an existing function
+	// DeleteFunction delete an existing function
 	DeleteFunction(tenant, namespace, name string) error
 
-	// Start all function instances
+	// StartFunction start all function instances
 	StartFunction(tenant, namespace, name string) error
 
-	// Start function instance
+	// StartFunctionWithID start function instance
 	StartFunctionWithID(tenant, namespace, name string, instanceID int) error
 
-	// Restart all function instances
+	// RestartFunction restart all function instances
 	RestartFunction(tenant, namespace, name string) error
 
-	// Restart function instance
+	// RestartFunctionWithID restart function instance
 	RestartFunctionWithID(tenant, namespace, name string, instanceID int) error
 
-	// Get the list of functions
+	// GetFunctions returns the list of functions
 	GetFunctions(tenant, namespace string) ([]string, error)
 
-	// Get the configuration for the specified function
+	// GetFunction returns the configuration for the specified function
 	GetFunction(tenant, namespace, name string) (FunctionConfig, error)
 
-	// Gets the current status of a function
+	// GetFunctionStatus returns the current status of a function
 	GetFunctionStatus(tenant, namespace, name string) (FunctionStatus, error)
 
-	// Gets the current status of a function instance
+	// GetFunctionStatusWithInstanceID returns the current status of a function instance
 	GetFunctionStatusWithInstanceID(tenant, namespace, name string, instanceID int) (FunctionInstanceStatusData, error)
 
-	// Gets the current stats of a function
+	// GetFunctionStats returns the current stats of a function
 	GetFunctionStats(tenant, namespace, name string) (FunctionStats, error)
 
-	// Gets the current stats of a function instance
+	// GetFunctionStatsWithInstanceID gets the current stats of a function instance
 	GetFunctionStatsWithInstanceID(tenant, namespace, name string, instanceID int) (FunctionInstanceStatsData, error)
 
-	// Fetch the current state associated with a Pulsar Function
+	// GetFunctionState fetch the current state associated with a Pulsar Function
 	//
 	// Response Example:
 	// 		{ "value : 12, version : 2"}
 	GetFunctionState(tenant, namespace, name, key string) (FunctionState, error)
 
-	// Puts the given state associated with a Pulsar Function
+	// PutFunctionState puts the given state associated with a Pulsar Function
 	PutFunctionState(tenant, namespace, name string, state FunctionState) error
 
-	// Triggers the function by writing to the input topic
+	// TriggerFunction triggers the function by writing to the input topic
 	TriggerFunction(tenant, namespace, name, topic, triggerValue, triggerFile string) (string, error)
 
-	// Update the configuration for a function.
+	// UpdateFunction updates the configuration for a function.
 	UpdateFunction(functionConfig *FunctionConfig, fileName string, updateOptions *UpdateOptions) error
 
-	// Update the configuration for a function.
+	// UpdateFunctionWithURL updates the configuration for a function.
 	//
 	// Update a function by providing url from which fun-pkg can be downloaded. supported url: http/file
 	// eg:
@@ -112,6 +114,7 @@ type functions struct {
 	basePath string
 }
 
+// Functions is used to access the functions endpoints
 func (c *client) Functions() Functions {
 	return &functions{
 		client:   c,