add comment for jsonrpc

protocol/invocation.go

@@ -29,15 +29,15 @@ type Invocation interface {
 	ParameterTypes() []reflect.Type
 	// ParameterValues gets invocation parameter values.
 	ParameterValues() []reflect.Value
-	// Arguments get arguments.
+	// Arguments gets arguments.
 	Arguments() []interface{}
-	// Reply gets request response
+	// Reply gets response of request
 	Reply() interface{}
 	// Attachments gets all attachments
 	Attachments() map[string]string
 	// AttachmentsByKey gets attachment by key , if nil then return default value
 	AttachmentsByKey(string, string) string
-	// Refer to dubbo 2.7.6.  It is different from attachment. It is used in internal process.
+	// Attributes refers to dubbo 2.7.6.  It is different from attachment. It is used in internal process.
 	Attributes() map[string]interface{}
 	// AttributeByKey gets attribute by key , if nil then return default value
 	AttributeByKey(string, interface{}) interface{}

protocol/invocation/rpcinvocation.go

@@ -31,7 +31,7 @@ import (
 // ///////////////////////////
 
 // todo: is it necessary to separate fields of consumer(provider) from RPCInvocation
-// RPCInvocation ...
+// RPCInvocation is invocation implement of RPC.
 type RPCInvocation struct {
 	methodName      string
 	parameterTypes  []reflect.Type
@@ -46,7 +46,7 @@ type RPCInvocation struct {
 	lock       sync.RWMutex
 }
 
-// NewRPCInvocation ...
+// NewRPCInvocation creates a RPC invocation.
 func NewRPCInvocation(methodName string, arguments []interface{}, attachments map[string]string) *RPCInvocation {
 	return &RPCInvocation{
 		methodName:  methodName,
@@ -56,7 +56,7 @@ func NewRPCInvocation(methodName string, arguments []interface{}, attachments ma
 	}
 }
 
-// NewRPCInvocationWithOptions ...
+// NewRPCInvocationWithOptions creates a RPC invocation with @opts.
 func NewRPCInvocationWithOptions(opts ...option) *RPCInvocation {
 	invo := &RPCInvocation{}
 	for _, opt := range opts {
@@ -68,42 +68,42 @@ func NewRPCInvocationWithOptions(opts ...option) *RPCInvocation {
 	return invo
 }
 
-// MethodName ...
+// MethodName gets RPC invocation method name.
 func (r *RPCInvocation) MethodName() string {
 	return r.methodName
 }
 
-// ParameterTypes ...
+// ParameterTypes gets RPC invocation parameter types.
 func (r *RPCInvocation) ParameterTypes() []reflect.Type {
 	return r.parameterTypes
 }
 
-// ParameterValues ...
+// ParameterValues gets RPC invocation parameter values.
 func (r *RPCInvocation) ParameterValues() []reflect.Value {
 	return r.parameterValues
 }
 
-// Arguments ...
+// Arguments gets RPC arguments.
 func (r *RPCInvocation) Arguments() []interface{} {
 	return r.arguments
 }
 
-// Reply ...
+// Reply gets response of RPC request.
 func (r *RPCInvocation) Reply() interface{} {
 	return r.reply
 }
 
-// SetReply ...
+// SetReply sets response of RPC request.
 func (r *RPCInvocation) SetReply(reply interface{}) {
 	r.reply = reply
 }
 
-// Attachments ...
+// Attachments gets all attachments of RPC.
 func (r *RPCInvocation) Attachments() map[string]string {
 	return r.attachments
 }
 
-// AttachmentsByKey ...
+// AttachmentsByKey gets RPC attachment by key , if nil then return default value.
 func (r *RPCInvocation) AttachmentsByKey(key string, defaultValue string) string {
 	r.lock.RLock()
 	defer r.lock.RUnlock()
@@ -117,12 +117,12 @@ func (r *RPCInvocation) AttachmentsByKey(key string, defaultValue string) string
 	return defaultValue
 }
 
-// get attributes
+// Attributes gets all attributes of RPC.
 func (r *RPCInvocation) Attributes() map[string]interface{} {
 	return r.attributes
 }
 
-// get attribute by key. If it is not exist, it will return default value
+// AttributeByKey gets attribute by @key. If it is not exist, it will return default value.
 func (r *RPCInvocation) AttributeByKey(key string, defaultValue interface{}) interface{} {
 	r.lock.RLock()
 	defer r.lock.RUnlock()
@@ -133,7 +133,7 @@ func (r *RPCInvocation) AttributeByKey(key string, defaultValue interface{}) int
 	return defaultValue
 }
 
-// SetAttachments ...
+// SetAttachments sets attribute by @key and @value.
 func (r *RPCInvocation) SetAttachments(key string, value string) {
 	r.lock.Lock()
 	defer r.lock.Unlock()
@@ -143,29 +143,24 @@ func (r *RPCInvocation) SetAttachments(key string, value string) {
 	r.attachments[key] = value
 }
 
-// SetAttribute. If Attributes is nil, it will be inited.
+// SetAttribute sets attribute by @key and @value.
 func (r *RPCInvocation) SetAttribute(key string, value interface{}) {
 	r.lock.Lock()
 	defer r.lock.Unlock()
 	r.attributes[key] = value
 }
 
-// Invoker ...
+// Invoker gets the invoker in current context.
 func (r *RPCInvocation) Invoker() protocol.Invoker {
 	return r.invoker
 }
 
-// SetInvoker ...
-func (r *RPCInvocation) SetInvoker() protocol.Invoker {
-	return r.invoker
-}
-
-// CallBack ...
+// CallBack sets RPC callback method.
 func (r *RPCInvocation) CallBack() interface{} {
 	return r.callBack
 }
 
-// SetCallBack ...
+// SetCallBack sets RPC callback method.
 func (r *RPCInvocation) SetCallBack(c interface{}) {
 	r.callBack = c
 }
@@ -176,56 +171,56 @@ func (r *RPCInvocation) SetCallBack(c interface{}) {
 
 type option func(invo *RPCInvocation)
 
-// WithMethodName ...
+// WithMethodName creates option with @methodName.
 func WithMethodName(methodName string) option {
 	return func(invo *RPCInvocation) {
 		invo.methodName = methodName
 	}
 }
 
-// WithParameterTypes ...
+// WithParameterTypes creates option with @parameterTypes.
 func WithParameterTypes(parameterTypes []reflect.Type) option {
 	return func(invo *RPCInvocation) {
 		invo.parameterTypes = parameterTypes
 	}
 }
 
-// WithParameterValues ...
+// WithParameterValues creates option with @parameterValues
 func WithParameterValues(parameterValues []reflect.Value) option {
 	return func(invo *RPCInvocation) {
 		invo.parameterValues = parameterValues
 	}
 }
 
-// WithArguments ...
+// WithArguments creates option with @arguments function.
 func WithArguments(arguments []interface{}) option {
 	return func(invo *RPCInvocation) {
 		invo.arguments = arguments
 	}
 }
 
-// WithReply ...
+// WithReply creates option with @reply function.
 func WithReply(reply interface{}) option {
 	return func(invo *RPCInvocation) {
 		invo.reply = reply
 	}
 }
 
-// WithCallBack ...
+// WithCallBack creates option with @callback function.
 func WithCallBack(callBack interface{}) option {
 	return func(invo *RPCInvocation) {
 		invo.callBack = callBack
 	}
 }
 
-// WithAttachments ...
+// WithAttachments creates option with @attachments.
 func WithAttachments(attachments map[string]string) option {
 	return func(invo *RPCInvocation) {
 		invo.attachments = attachments
 	}
 }
 
-// WithInvoker ...
+// WithInvoker creates option with @invoker.
 func WithInvoker(invoker protocol.Invoker) option {
 	return func(invo *RPCInvocation) {
 		invo.invoker = invoker

protocol/jsonrpc/http.go

@@ -63,7 +63,7 @@ type Request struct {
 // HTTP Client
 // ////////////////////////////////////////////
 
-// HTTPOptions ...
+// HTTPOptions is a HTTP option include HandshakeTimeout and HTTPTimeout.
 type HTTPOptions struct {
 	HandshakeTimeout time.Duration
 	HTTPTimeout      time.Duration
@@ -74,13 +74,13 @@ var defaultHTTPOptions = HTTPOptions{
 	HTTPTimeout:      3 * time.Second,
 }
 
-// HTTPClient ...
+// HTTPClient is a HTTP client ,include ID and options.
 type HTTPClient struct {
 	ID      int64
 	options HTTPOptions
 }
 
-// NewHTTPClient ...
+// NewHTTPClient creates a new HTTP client with HTTPOptions.
 func NewHTTPClient(opt *HTTPOptions) *HTTPClient {
 	if opt == nil {
 		opt = &defaultHTTPOptions
@@ -100,7 +100,7 @@ func NewHTTPClient(opt *HTTPOptions) *HTTPClient {
 	}
 }
 
-// NewRequest ...
+// NewRequest creates a new HTTP request with @service ,@method and @arguments.
 func (c *HTTPClient) NewRequest(service common.URL, method string, args interface{}) *Request {
 
 	return &Request{
@@ -114,7 +114,7 @@ func (c *HTTPClient) NewRequest(service common.URL, method string, args interfac
 	}
 }
 
-// Call ...
+// Call makes a HTTP call with @ctx , @service ,@req and @rsp
 func (c *HTTPClient) Call(ctx context.Context, service common.URL, req *Request, rsp interface{}) error {
 	// header
 	httpHeader := http.Header{}

protocol/jsonrpc/json.go

@@ -37,7 +37,7 @@ const (
 	VERSION = "2.0"
 )
 
-// CodecData ...
+// CodecData is codec data for json RPC.
 type CodecData struct {
 	ID     int64
 	Method string
@@ -64,6 +64,7 @@ type Error struct {
 	Data    interface{} `json:"data,omitempty"`
 }
 
+// Error decodes response error for a string.
 func (e *Error) Error() string {
 	buf, err := json.Marshal(e)
 	if err != nil {
@@ -114,6 +115,7 @@ func newJsonClientCodec() *jsonClientCodec {
 	}
 }
 
+// Write codec data as byte.
 func (c *jsonClientCodec) Write(d *CodecData) ([]byte, error) {
 	// If return error: it will be returned as is for this call.
 	// Allow param to be only Array, Slice, Map or Struct.
@@ -170,6 +172,7 @@ func (c *jsonClientCodec) Write(d *CodecData) ([]byte, error) {
 	return buf.Bytes(), nil
 }
 
+// Read bytes as structured data
 func (c *jsonClientCodec) Read(streamBytes []byte, x interface{}) error {
 	c.rsp.reset()
 
@@ -223,6 +226,7 @@ func (r *serverRequest) reset() {
 	}
 }
 
+// UnmarshalJSON unmarshals JSON for server request.
 func (r *serverRequest) UnmarshalJSON(raw []byte) error {
 	r.reset()
 
@@ -281,7 +285,7 @@ type serverResponse struct {
 	Error   interface{}      `json:"error,omitempty"`
 }
 
-// ServerCodec ...
+// ServerCodec is codec data for request server.
 type ServerCodec struct {
 	req serverRequest
 }
@@ -296,7 +300,7 @@ func newServerCodec() *ServerCodec {
 	return &ServerCodec{}
 }
 
-// ReadHeader ...
+// ReadHeader reads header and unmarshal to server codec
 func (c *ServerCodec) ReadHeader(header map[string]string, body []byte) error {
 	if header["HttpMethod"] != "POST" {
 		return &Error{Code: -32601, Message: "Method not found"}
@@ -328,7 +332,7 @@ func (c *ServerCodec) ReadHeader(header map[string]string, body []byte) error {
 	return nil
 }
 
-// ReadBody ...
+// ReadBody reads @x as request body.
 func (c *ServerCodec) ReadBody(x interface{}) error {
 	// If x!=nil and return error e:
 	// - Write() will be called with e.Error() in r.Error
@@ -339,7 +343,7 @@ func (c *ServerCodec) ReadBody(x interface{}) error {
 		return nil
 	}
 
-	// 在这里把请求参数json 字符串转换成了相应的struct
+	// the request parameter JSON string is converted to the corresponding struct
 	params := []byte(*c.req.Params)
 	if err := json.Unmarshal(*c.req.Params, x); err != nil {
 		// Note: if c.request.Params is nil it's not an error, it's an optional member.
@@ -362,7 +366,7 @@ func (c *ServerCodec) ReadBody(x interface{}) error {
 	return nil
 }
 
-// NewError ...
+// NewError creates a error with @code and @message
 func NewError(code int, message string) *Error {
 	return &Error{Code: code, Message: message}
 }
@@ -380,6 +384,7 @@ func newError(message string) *Error {
 	}
 }
 
+// Write responses as byte
 func (c *ServerCodec) Write(errMsg string, x interface{}) ([]byte, error) {
 	// If return error: nothing happens.
 	// In r.Error will be "" or .Error() of error returned by:

protocol/jsonrpc/jsonrpc_exporter.go

@@ -28,19 +28,19 @@ import (
 	"github.com/apache/dubbo-go/protocol"
 )
 
-// JsonrpcExporter ...
+// JsonrpcExporter is JSON RPC exporter and  extends from base invoker.
 type JsonrpcExporter struct {
 	protocol.BaseExporter
 }
 
-// NewJsonrpcExporter ...
+// NewJsonrpcExporter creates JSON RPC exporter with @key, @invoker and @exporterMap
 func NewJsonrpcExporter(key string, invoker protocol.Invoker, exporterMap *sync.Map) *JsonrpcExporter {
 	return &JsonrpcExporter{
 		BaseExporter: *protocol.NewBaseExporter(key, invoker, exporterMap),
 	}
 }
 
-// Unexport ...
+// Unexport exported JSON RPC service.
 func (je *JsonrpcExporter) Unexport() {
 	serviceId := je.GetInvoker().GetUrl().GetParam(constant.BEAN_NAME_KEY, "")
 	interfaceName := je.GetInvoker().GetUrl().GetParam(constant.INTERFACE_KEY, "")

protocol/jsonrpc/jsonrpc_invoker.go

@@ -29,13 +29,13 @@ import (
 	invocation_impl "github.com/apache/dubbo-go/protocol/invocation"
 )
 
-// JsonrpcInvoker ...
+// JsonrpcInvoker is JSON RPC invoker
 type JsonrpcInvoker struct {
 	protocol.BaseInvoker
 	client *HTTPClient
 }
 
-// NewJsonrpcInvoker ...
+// NewJsonrpcInvoker creates JSON RPC invoker with @url and @client
 func NewJsonrpcInvoker(url common.URL, client *HTTPClient) *JsonrpcInvoker {
 	return &JsonrpcInvoker{
 		BaseInvoker: *protocol.NewBaseInvoker(url),
@@ -43,7 +43,7 @@ func NewJsonrpcInvoker(url common.URL, client *HTTPClient) *JsonrpcInvoker {
 	}
 }
 
-// Invoke ...
+// Invoke the JSON RPC invocation and return result.
 func (ji *JsonrpcInvoker) Invoke(ctx context.Context, invocation protocol.Invocation) protocol.Result {
 
 	var (

protocol/jsonrpc/jsonrpc_protocol.go

@@ -44,14 +44,14 @@ func init() {
 
 var jsonrpcProtocol *JsonrpcProtocol
 
-// JsonrpcProtocol ...
+// JsonrpcProtocol is JSON RPC protocol.
 type JsonrpcProtocol struct {
 	protocol.BaseProtocol
 	serverMap  map[string]*Server
 	serverLock sync.Mutex
 }
 
-// NewJsonrpcProtocol ...
+// NewJsonrpcProtocol creates JSON RPC protocol
 func NewJsonrpcProtocol() *JsonrpcProtocol {
 	return &JsonrpcProtocol{
 		BaseProtocol: protocol.NewBaseProtocol(),
@@ -59,7 +59,7 @@ func NewJsonrpcProtocol() *JsonrpcProtocol {
 	}
 }
 
-// Export ...
+// Export JSON RPC service  for remote invocation
 func (jp *JsonrpcProtocol) Export(invoker protocol.Invoker) protocol.Exporter {
 	url := invoker.GetUrl()
 	serviceKey := strings.TrimPrefix(url.Path, "/")
@@ -74,7 +74,7 @@ func (jp *JsonrpcProtocol) Export(invoker protocol.Invoker) protocol.Exporter {
 	return exporter
 }
 
-// Refer ...
+// Refer a remote JSON PRC service from registry
 func (jp *JsonrpcProtocol) Refer(url common.URL) protocol.Invoker {
 	//default requestTimeout
 	var requestTimeout = config.GetConsumerConfig().RequestTimeout
@@ -93,7 +93,7 @@ func (jp *JsonrpcProtocol) Refer(url common.URL) protocol.Invoker {
 	return invoker
 }
 
-// Destroy ...
+// Destroy will destroy all invoker and exporter, so it only is called once.
 func (jp *JsonrpcProtocol) Destroy() {
 	logger.Infof("jsonrpcProtocol destroy.")
 
@@ -125,7 +125,7 @@ func (jp *JsonrpcProtocol) openServer(url common.URL) {
 	}
 }
 
-// GetProtocol ...
+// GetProtocol gets JSON RPC protocol.
 func GetProtocol() protocol.Protocol {
 	if jsonrpcProtocol == nil {
 		jsonrpcProtocol = NewJsonrpcProtocol()

protocol/jsonrpc/server.go

@@ -59,7 +59,7 @@ const (
 	PathPrefix = byte('/')
 )
 
-// Server ...
+// Server is JSON RPC server wrapper
 type Server struct {
 	done chan struct{}
 	once sync.Once
@@ -69,7 +69,7 @@ type Server struct {
 	timeout time.Duration
 }
 
-// NewServer ...
+// NewServer creates new JSON RPC server.
 func NewServer() *Server {
 	return &Server{
 		done: make(chan struct{}),
@@ -228,7 +228,7 @@ func accept(listener net.Listener, fn func(net.Conn)) error {
 	}
 }
 
-// Start ...
+// Start JSON RPC server then ready for accept request.
 func (s *Server) Start(url common.URL) {
 	listener, err := net.Listen("tcp", url.Location)
 	if err != nil {
@@ -255,7 +255,7 @@ func (s *Server) Start(url common.URL) {
 	}()
 }
 
-// Stop ...
+// Stop JSON RPC server, just can be call once.
 func (s *Server) Stop() {
 	s.once.Do(func() {
 		close(s.done)