From dd8c7b94dee84141f16222e4ff2c5c7b118828e2 Mon Sep 17 00:00:00 2001
From: v2ray <admin@v2ray.com>
Date: Sat, 6 Feb 2016 10:54:41 +0100
Subject: [PATCH] doc for port

---
 common/net/port.go | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/common/net/port.go b/common/net/port.go
index 97c3b1126..1f04a6f85 100644
--- a/common/net/port.go
+++ b/common/net/port.go
@@ -12,12 +12,17 @@ var (
 	ErrorInvalidPortRange = errors.New("Invalid port range.")
 )
 
+// Port represents a network port in TCP and UDP protocol.
 type Port serial.Uint16Literal
 
+// PortFromBytes converts a byte array to a Port, assuming bytes are in big endian order.
+// @unsafe Caller must ensure that the byte array has at least 2 elements.
 func PortFromBytes(port []byte) Port {
 	return Port(serial.BytesLiteral(port).Uint16Value())
 }
 
+// PortFromInt converts an integer to a Port.
+// @error when the integer is not positive or larger then 65535
 func PortFromInt(v int) (Port, error) {
 	if v <= 0 || v > 65535 {
 		return Port(0), ErrorInvalidPortRange
@@ -25,6 +30,8 @@ func PortFromInt(v int) (Port, error) {
 	return Port(v), nil
 }
 
+// PortFromString converts a string to a Port.
+// @error when the string is not an integer or the integral value is a not a valid Port.
 func PortFromString(s string) (Port, error) {
 	v, err := strconv.Atoi(s)
 	if err != nil {
@@ -33,23 +40,28 @@ func PortFromString(s string) (Port, error) {
 	return PortFromInt(v)
 }
 
+// Value return the correspoding uint16 value of this Port.
 func (this Port) Value() uint16 {
 	return uint16(this)
 }
 
+// Bytes returns the correspoding bytes of this Port, in big endian order.
 func (this Port) Bytes() []byte {
 	return serial.Uint16Literal(this).Bytes()
 }
 
+// String returns the string presentation of this Port.
 func (this Port) String() string {
 	return serial.Uint16Literal(this).String()
 }
 
+// PortRange represents a range of ports.
 type PortRange struct {
 	From Port
 	To   Port
 }
 
+// Contains returns true if the given port is within the range of this PortRange.
 func (this PortRange) Contains(port Port) bool {
 	return this.From <= port && port <= this.To
 }