Merge pull request googollee#100 from 1lann/master

Clarify documentation and argument names

Author: googollee

adapter.go

@@ -1,16 +1,16 @@
 package socketio
 
-// BroadcastAdaptor is the adaptor to handle broadcast.
+// BroadcastAdaptor is the adaptor to handle broadcasts.
 type BroadcastAdaptor interface {
 
-	// Join lets socket join the t room.
+	// Join causes the socket to join a room.
 	Join(room string, socket Socket) error
 
-	// Leave let socket leave the room.
+	// Leave causes the socket to leave a room.
 	Leave(room string, socket Socket) error
 
-	// Send will send the message with args to room. If ignore is not nil, it won't send to the socket ignore.
-	Send(ignore Socket, room, message string, args ...interface{}) error
+	// Send will send an event with args to the room. If "ignore" is not nil, the event will be excluded from being sent to "ignore".
+	Send(ignore Socket, room, event string, args ...interface{}) error
 }
 
 var newBroadcast = newBroadcastDefault
@@ -45,13 +45,13 @@ func (b broadcast) Leave(room string, socket Socket) error {
 	return nil
 }
 
-func (b broadcast) Send(ignore Socket, room, message string, args ...interface{}) error {
+func (b broadcast) Send(ignore Socket, room, event string, args ...interface{}) error {
 	sockets := b[room]
 	for id, s := range sockets {
 		if ignore != nil && ignore.Id() == id {
 			continue
 		}
-		s.Emit(message, args...)
+		s.Emit(event, args...)
 	}
 	return nil
 }

attachment.go

@@ -8,7 +8,7 @@ import (
 	"reflect"
 )
 
-// Attachment is an attachment handler used in emit args. All attachments will send as binary in transport layer. When use attachment, make sure use as pointer.
+// Attachment is an attachment handler used in emit args. All attachments will be sent as binary data in the transport layer. When using an attachment, make sure it is a pointer.
 //
 // For example:
 //
@@ -30,8 +30,6 @@ import (
 //         b, _ := ioutil.ReadAll(arg.File.Data)
 //     })
 type Attachment struct {
-
-	// Data is the ReadWriter of the attachment data.
 	Data io.ReadWriter
 	num  int
 }

example/asset/socket.io.js

@@ -2512,7 +2512,7 @@ JSONPPolling.prototype.doPoll = function () {
   this.script = script;
 
   var isUAgecko = 'undefined' != typeof navigator && /gecko/i.test(navigator.userAgent);
-  
+
   if (isUAgecko) {
     setTimeout(function () {
       var iframe = document.createElement('iframe');
@@ -4548,7 +4548,7 @@ module.exports = hasBinary;
 
 function hasBinary(data) {
 
-  function recursiveCheckForBinary(obj) { 
+  function recursiveCheckForBinary(obj) {
     if (!obj) return false;
 
     if ( (global.Buffer && Buffer.isBuffer(obj)) ||

handler.go

@@ -19,13 +19,13 @@ func newBaseHandler(name string, broadcast BroadcastAdaptor) *baseHandler {
 	}
 }
 
-// On registers the function f to handle message.
-func (h *baseHandler) On(message string, f interface{}) error {
+// On registers the function f to handle an event.
+func (h *baseHandler) On(event string, f interface{}) error {
 	c, err := newCaller(f)
 	if err != nil {
 		return err
 	}
-	h.events[message] = c
+	h.events[event] = c
 	return nil
 }
 
@@ -52,7 +52,7 @@ func newSocketHandler(s *socket, base *baseHandler) *socketHandler {
 	}
 }
 
-func (h *socketHandler) Emit(message string, args ...interface{}) error {
+func (h *socketHandler) Emit(event string, args ...interface{}) error {
 	var c *caller
 	if l := len(args); l > 0 {
 		fv := reflect.ValueOf(args[l-1])
@@ -65,7 +65,7 @@ func (h *socketHandler) Emit(message string, args ...interface{}) error {
 			args = args[:l-1]
 		}
 	}
-	args = append([]interface{}{message}, args...)
+	args = append([]interface{}{event}, args...)
 	if c != nil {
 		id, err := h.socket.sendId(args)
 		if err != nil {
@@ -112,12 +112,12 @@ func (h *socketHandler) LeaveAll() error {
 	return nil
 }
 
-func (h *baseHandler) BroadcastTo(room, message string, args ...interface{}) error {
-	return h.broadcast.Send(nil, h.broadcastName(room), message, args...)
+func (h *baseHandler) BroadcastTo(room, event string, args ...interface{}) error {
+	return h.broadcast.Send(nil, h.broadcastName(room), event, args...)
 }
 
-func (h *socketHandler) BroadcastTo(room, message string, args ...interface{}) error {
-	return h.baseHandler.broadcast.Send(h.socket, h.broadcastName(room), message, args...)
+func (h *socketHandler) BroadcastTo(room, event string, args ...interface{}) error {
+	return h.baseHandler.broadcast.Send(h.socket, h.broadcastName(room), event, args...)
 }
 
 func (h *baseHandler) broadcastName(room string) string {

main.go

@@ -1,6 +1,6 @@
 /*
-go-socket.io is the implement of socket.io in golang.
+go-socket.io is a server implementation of socket.io in golang.
 
-It is compatible with node.js implement.
+It is compatible with the official Node.js implementation.
 */
 package socketio

namespace.go

@@ -1,16 +1,16 @@
 package socketio
 
-// Namespace is the name space of socket.io handler.
+// Namespace is the name space of a socket.io handler.
 type Namespace interface {
 
-	// Name returns the name of namespace.
+	// Name returns the name of the namespace.
 	Name() string
 
 	// Of returns the namespace with given name.
 	Of(name string) Namespace
 
-	// On registers the function f to handle message.
-	On(message string, f interface{}) error
+	// On registers the function f to handle an event.
+	On(event string, f interface{}) error
 }
 
 type namespace struct {

server.go

@@ -13,7 +13,7 @@ type Server struct {
 	eio       *engineio.Server
 }
 
-// NewServer returns the server supported given transports. If transports is nil, server will use ["polling", "websocket"] as default.
+// NewServer returns the server supported given transports. If transports is nil, the server will use ["polling", "websocket"] as default.
 func NewServer(transportNames []string) (*Server, error) {
 	eio, err := engineio.NewServer(transportNames)
 	if err != nil {
@@ -27,57 +27,57 @@ func NewServer(transportNames []string) (*Server, error) {
 	return ret, nil
 }
 
-// SetPingTimeout sets the timeout of ping. When time out, server will close connection. Default is 60s.
+// SetPingTimeout sets the timeout of a connection ping. When it times out, the server will close the connection with the client. Default is 60s.
 func (s *Server) SetPingTimeout(t time.Duration) {
 	s.eio.SetPingTimeout(t)
 }
 
-// SetPingInterval sets the interval of ping. Default is 25s.
+// SetPingInterval sets the interval of pings. Default is 25s.
 func (s *Server) SetPingInterval(t time.Duration) {
 	s.eio.SetPingInterval(t)
 }
 
-// SetMaxConnection sets the max connetion. Default is 1000.
+// SetMaxConnection sets the maximum number of connections with clients. Default is 1000.
 func (s *Server) SetMaxConnection(n int) {
 	s.eio.SetMaxConnection(n)
 }
 
-// SetAllowRequest sets the middleware function when establish connection. If it return non-nil, connection won't be established. Default will allow all request.
+// SetAllowRequest sets the middleware function when a connection is established. If a non-nil value is returned, the connection won't be established. Default will allow all connections.
 func (s *Server) SetAllowRequest(f func(*http.Request) error) {
 	s.eio.SetAllowRequest(f)
 }
 
-// SetAllowUpgrades sets whether server allows transport upgrade. Default is true.
+// SetAllowUpgrades sets whether server allows transport upgrades. Default is true.
 func (s *Server) SetAllowUpgrades(allow bool) {
 	s.eio.SetAllowUpgrades(allow)
 }
 
-// SetCookie sets the name of cookie which used by engine.io. Default is "io".
+// SetCookie sets the name of the cookie used by engine.io. Default is "io".
 func (s *Server) SetCookie(prefix string) {
 	s.eio.SetCookie(prefix)
 }
 
-// SetNewId sets the callback func to generate new connection id. By default, id is generated from remote addr + current time stamp
+// SetNewId sets the callback func to generate new connection id. By default, id is generated from remote address + current time stamp
 func (s *Server) SetNewId(f func(*http.Request) string) {
 	s.eio.SetNewId(f)
 }
 
-// SetSessionsManager sets the sessions as server's session manager. Default sessions is single process manager. You can custom it as load balance.
+// SetSessionsManager sets the sessions as server's session manager. Default sessions is a single process manager. You can customize it as a load balancer.
 func (s *Server) SetSessionManager(sessions engineio.Sessions) {
 	s.eio.SetSessionManager(sessions)
 }
 
-// SetAdaptor sets the adaptor of broadcast. Default is in-process broadcast implement.
+// SetAdaptor sets the adaptor of broadcast. Default is an in-process broadcast implementation.
 func (s *Server) SetAdaptor(adaptor BroadcastAdaptor) {
 	s.namespace = newNamespace(adaptor)
 }
 
-// ServeHTTP handles http request.
+// ServeHTTP handles http requests.
 func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	s.eio.ServeHTTP(w, r)
 }
 
-// Server level broadcasts function.
+// BroadcastTo is a server level broadcast function.
 func (s *Server) BroadcastTo(room, message string, args ...interface{}) {
 	s.namespace.BroadcastTo(room, message, args...)
 }

socket.go

@@ -18,20 +18,20 @@ type Socket interface {
 	// Request returns the first http request when established connection.
 	Request() *http.Request
 
-	// On registers the function f to handle message.
-	On(message string, f interface{}) error
+	// On registers the function f to handle an event.
+	On(event string, f interface{}) error
 
-	// Emit emits the message with given args.
-	Emit(message string, args ...interface{}) error
+	// Emit emits an event with given args.
+	Emit(event string, args ...interface{}) error
 
 	// Join joins the room.
 	Join(room string) error
 
 	// Leave leaves the room.
 	Leave(room string) error
 
-	// BroadcastTo broadcasts the message to the room with given args.
-	BroadcastTo(room, message string, args ...interface{}) error
+	// BroadcastTo broadcasts an event to the room with given args.
+	BroadcastTo(room, event string, args ...interface{}) error
 }
 
 type socket struct {
@@ -57,11 +57,11 @@ func (s *socket) Request() *http.Request {
 	return s.conn.Request()
 }
 
-func (s *socket) Emit(message string, args ...interface{}) error {
-	if err := s.socketHandler.Emit(message, args...); err != nil {
+func (s *socket) Emit(event string, args ...interface{}) error {
+	if err := s.socketHandler.Emit(event, args...); err != nil {
 		return err
 	}
-	if message == "disconnect" {
+	if event == "disconnect" {
 		s.conn.Close()
 	}
 	return nil