[dubbo-go] 05/13: add some comments

[ba...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

baze pushed a commit to branch 1.4
in repository https://gitbox.apache.org/repos/asf/dubbo-go.git

commit f2949db91e69f536316a435eaa9433e539947bbe
Author: Patrick <dr...@foxmail.com>
AuthorDate: Wed Apr 1 20:04:31 2020 +0800

    add some comments
---
 protocol/rest/client/client_impl/resty_client.go   |  1 +
 protocol/rest/client/rest_client.go                |  3 +++
 protocol/rest/server/rest_server.go                | 20 +++++++++++++---
 .../rest/server/server_impl/go_restful_server.go   | 27 ++++++++++++++++------
 4 files changed, 41 insertions(+), 10 deletions(-)

diff --git a/protocol/rest/client/client_impl/resty_client.go b/protocol/rest/client/client_impl/resty_client.go
index 9e0c80c..bfd7445 100644
--- a/protocol/rest/client/client_impl/resty_client.go
+++ b/protocol/rest/client/client_impl/resty_client.go
@@ -40,6 +40,7 @@ func init() {
 	extension.SetRestClient(constant.DEFAULT_REST_CLIENT, NewRestyClient)
 }
 
+// A rest client implement by Resty
 type RestyClient struct {
 	client *resty.Client
 }
diff --git a/protocol/rest/client/rest_client.go b/protocol/rest/client/rest_client.go
index 5be4bb3..47d17c6 100644
--- a/protocol/rest/client/rest_client.go
+++ b/protocol/rest/client/rest_client.go
@@ -22,11 +22,13 @@ import (
 	"time"
 )
 
+// Some rest options
 type RestOptions struct {
 	RequestTimeout time.Duration
 	ConnectTimeout time.Duration
 }
 
+// Client request
 type RestClientRequest struct {
 	Header      http.Header
 	Location    string
@@ -37,6 +39,7 @@ type RestClientRequest struct {
 	Body        interface{}
 }
 
+// User can implement this client interface to send request
 type RestClient interface {
 	Do(request *RestClientRequest, res interface{}) error
 }
diff --git a/protocol/rest/server/rest_server.go b/protocol/rest/server/rest_server.go
index 7fb0560..60f0dab 100644
--- a/protocol/rest/server/rest_server.go
+++ b/protocol/rest/server/rest_server.go
@@ -38,33 +38,47 @@ import (
 )
 
 type RestServer interface {
+	// start rest server
 	Start(url common.URL)
+	// deploy a http api
 	Deploy(restMethodConfig *rest_config.RestMethodConfig, routeFunc func(request RestServerRequest, response RestServerResponse))
+	// unDeploy a http api
 	UnDeploy(restMethodConfig *rest_config.RestMethodConfig)
+	// destroy rest server
 	Destroy()
 }
 
 // RestServerRequest interface
 type RestServerRequest interface {
+	// Get the Ptr of http.Request
 	RawRequest() *http.Request
+	// Get the path parameter by name
 	PathParameter(name string) string
+	// Get the map of the path parameters
 	PathParameters() map[string]string
+	// Get the query parameter by name
 	QueryParameter(name string) string
+	// Get the map of query parameters
 	QueryParameters(name string) []string
+	// Get the body parameter of name
 	BodyParameter(name string) (string, error)
+	// Get the header parameter of name
 	HeaderParameter(name string) string
+	// ReadEntity checks the Accept header and reads the content into the entityPointer.
 	ReadEntity(entityPointer interface{}) error
 }
 
 // RestServerResponse interface
 type RestServerResponse interface {
-	Header() http.Header
-	Write([]byte) (int, error)
-	WriteHeader(statusCode int)
+	http.ResponseWriter
+	// WriteError writes the http status and the error string on the response. err can be nil.
+	// Return an error if writing was not succesful.
 	WriteError(httpStatus int, err error) (writeErr error)
+	// WriteEntity marshals the value using the representation denoted by the Accept Header.
 	WriteEntity(value interface{}) error
 }
 
+// A route function will be invoked by http server
 func GetRouteFunc(invoker protocol.Invoker, methodConfig *rest_config.RestMethodConfig) func(req RestServerRequest, resp RestServerResponse) {
 	return func(req RestServerRequest, resp RestServerResponse) {
 		var (
diff --git a/protocol/rest/server/server_impl/go_restful_server.go b/protocol/rest/server/server_impl/go_restful_server.go
index 9163d3a..00b644f 100644
--- a/protocol/rest/server/server_impl/go_restful_server.go
+++ b/protocol/rest/server/server_impl/go_restful_server.go
@@ -41,20 +41,24 @@ import (
 )
 
 func init() {
-	extension.SetRestServer(constant.DEFAULT_REST_SERVER, GetNewGoRestfulServer)
+	extension.SetRestServer(constant.DEFAULT_REST_SERVER, NewGoRestfulServer)
 }
 
 var filterSlice []restful.FilterFunction
 
+// A rest server implement by go-restful
 type GoRestfulServer struct {
 	srv       *http.Server
 	container *restful.Container
 }
 
-func NewGoRestfulServer() *GoRestfulServer {
+// A constructor of GoRestfulServer
+func NewGoRestfulServer() server.RestServer {
 	return &GoRestfulServer{}
 }
 
+// Start go-restful server
+// It will add all go-restful filters
 func (grs *GoRestfulServer) Start(url common.URL) {
 	grs.container = restful.NewContainer()
 	for _, filter := range filterSlice {
@@ -76,6 +80,8 @@ func (grs *GoRestfulServer) Start(url common.URL) {
 	}()
 }
 
+// Publish a http api in go-restful server
+// The routeFunc should be invoked when the server receive a request
 func (grs *GoRestfulServer) Deploy(restMethodConfig *config.RestMethodConfig, routeFunc func(request server.RestServerRequest, response server.RestServerResponse)) {
 	ws := new(restful.WebService)
 	rf := func(req *restful.Request, resp *restful.Response) {
@@ -89,6 +95,7 @@ func (grs *GoRestfulServer) Deploy(restMethodConfig *config.RestMethodConfig, ro
 
 }
 
+// Delete a http api in go-restful server
 func (grs *GoRestfulServer) UnDeploy(restMethodConfig *config.RestMethodConfig) {
 	ws := new(restful.WebService)
 	ws.Path(restMethodConfig.Path)
@@ -98,6 +105,7 @@ func (grs *GoRestfulServer) UnDeploy(restMethodConfig *config.RestMethodConfig)
 	}
 }
 
+// Destroy the go-restful server
 func (grs *GoRestfulServer) Destroy() {
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 	defer cancel()
@@ -107,11 +115,7 @@ func (grs *GoRestfulServer) Destroy() {
 	logger.Infof("[Go Restful] Server exiting")
 }
 
-func GetNewGoRestfulServer() server.RestServer {
-	return NewGoRestfulServer()
-}
-
-// Let user addFilter
+// Let user add the http server of go-restful
 // addFilter should before config.Load()
 func AddGoRestfulServerFilter(filterFuc restful.FilterFunction) {
 	filterSlice = append(filterSlice, filterFuc)
@@ -123,38 +127,47 @@ type GoRestfulRequestAdapter struct {
 	request *restful.Request
 }
 
+// A constructor of GoRestfulRequestAdapter
 func NewGoRestfulRequestAdapter(request *restful.Request) *GoRestfulRequestAdapter {
 	return &GoRestfulRequestAdapter{request: request}
 }
 
+// A adapter function of server.RestServerRequest's RawRequest
 func (grra *GoRestfulRequestAdapter) RawRequest() *http.Request {
 	return grra.request.Request
 }
 
+// A adapter function of server.RestServerRequest's PathParameter
 func (grra *GoRestfulRequestAdapter) PathParameter(name string) string {
 	return grra.request.PathParameter(name)
 }
 
+// A adapter function of server.RestServerRequest's QueryParameter
 func (grra *GoRestfulRequestAdapter) PathParameters() map[string]string {
 	return grra.request.PathParameters()
 }
 
+// A adapter function of server.RestServerRequest's QueryParameters
 func (grra *GoRestfulRequestAdapter) QueryParameter(name string) string {
 	return grra.request.QueryParameter(name)
 }
 
+// A adapter function of server.RestServerRequest's QueryParameters
 func (grra *GoRestfulRequestAdapter) QueryParameters(name string) []string {
 	return grra.request.QueryParameters(name)
 }
 
+// A adapter function of server.RestServerRequest's BodyParameter
 func (grra *GoRestfulRequestAdapter) BodyParameter(name string) (string, error) {
 	return grra.request.BodyParameter(name)
 }
 
+// A adapter function of server.RestServerRequest's HeaderParameter
 func (grra *GoRestfulRequestAdapter) HeaderParameter(name string) string {
 	return grra.request.HeaderParameter(name)
 }
 
+// A adapter func of server.RestServerRequest's ReadEntity
 func (grra *GoRestfulRequestAdapter) ReadEntity(entityPointer interface{}) error {
 	return grra.request.ReadEntity(entityPointer)
 }